I've seen some confusion regarding the role of docrails with regard to
the API. Many people have the impression that documentation goes
through docrails, but this is not exact. Let me share these remarks
with you all:
The main source of API docs is master.
When a patch to master adds stuff that belongs to the public
interface, the patch should include proper tests and rdoc. You do not
send the code through master and then document in docrails, rather
everything goes in the original patch for it to be complete.
If the patch renames/moves/deprecates/... the source tree would be
additionally ack'ed to find instances of the previous idiom. The
examples in the API docs have to implicitly show what is idiomatic in
modern Rails to the reader and may need update. That goes also with
It is difficult to have a global uniform style with contributions by
so many people (we're approaching 1500!), or that everybody follows
precisely the API conventions
and so it could be the case that someone in the doc team then
copy-edits a little, but that is minor in general.
So, what about docrails? The purpose of docrails is to be able to
*patch* the docs bypassing LH. For example, if you see an error in the
API and you have commit in docrails (otherwise ask lifo), you just
fire up a console, edit, and push. Fixed.
Since going through docrails is just a shortcut for something that
would go trough LH otherwise, merges from docrails into master are now
normal and Rails Contributors gives you credit, as if the doc patch
went through master (though if several trivial commits are pushed it
could be the case they get squashed to keep some balance).