rails offline documentation

Running `rake doc:rails` from a Rails project root should drop it into
your doc/ directory (if I remember correctly!).

--Jeremy

In a related question… Is the RDoc updated regularly on Edge Rails or is it done in chunks as things progress to a significant level? I’d hate to be depending on or searching needlessly through RDoc that doesn’t reflect the current codebase. [Hope that doesn’t sounds snotty.]

RSL

I read a while back that http://caboo.se/doc.html is generated off
trunk 3 times a day.

This might be what your looking for...

I’m sorry I didn’t make my question clear. I meant to ask if the RDoc was changed at the same time code was changed, ie. if ActiveRecord#find had some new functionality in a new svn revision should I expect the RDoc to reflect the new code or not? Hope that was clearer. I can be a little obtuse sometimes.

RSL

If you're generating it yourself by running rake doc:rails in the root
of your rails app then it won't change automatically if you update
Rails.

I think other posters are missing what you're asking, but I didn't.
And the answer is...it depends.

ActiveResource, for example, has been in the trunk for a little while
but only recently got documentation at all. Other things will have
their RDocs changed as the code is changed. Typically patches that
are committed are required to have documentation and tests associated
with them, so usually this shouldn't be a problem. :slight_smile:

--Jeremy

Looks like I’m still not making myself clear. I myself have documented my own code on some projects with RDoc. However, sometimes I changed the actual code without changing the RDoc [which is in the comments basically] so my RDoc often made reference to code or scenarios which were no longer appropriate. I would notice this and then update the RDoc. I’m trying to ask if the RDoc [the actual commented out lines inside the source code] gets updated when there are changes to the source or is it easier/more feasible to just go through and edit the RDoc when the code gets more stable? Hopefully that was specific enough a question.

RSL

Zack Chandler wrote:

You need to re-generate the documentation files every time there is a
change. There aren't automatically updated in any sense. This means
that if you change a method name or something you still have to
regenerate the documentation, even if you don't touch the RDocs.

--Jeremy

Russell Norris wrote:

Looks like I'm still not making myself clear. I myself have documented my own code on some projects with RDoc. However, sometimes I changed the actual code without changing the RDoc [which is in the comments basically] so my RDoc often made reference to code or scenarios which were no longer appropriate. I would notice this and then update the RDoc. I'm trying to ask if the RDoc [the actual commented out lines inside the source code] gets updated when there are changes to the source or is it easier/more feasible to just go through and edit the RDoc when the code gets more stable? Hopefully _that_ was specific enough a question.

RSL

Sorry, posted my last message before I saw this. I got trigger happy!

You're referring to your own app's docs, not rails documentation itself. The subject was the key to that confusion. :slight_smile:

Forgive me if I'm still unclear on your question, but rdoc generates documentation from your code. The meat (or actual content) of the documentation comes from your comments.

if you have

def my_method(foo, bar)
   # example my_method('pootie', 'tang')
end

and later you change it to accept only 1 option instead, the comment (and hence the docs) will stay the same unless you change it.
So the your options are:
A.) change comments as you change code
B.) wait to comment until you're more stable (or finished)

In the ideal world, we'd all use A