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 the patch.
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 (http://wiki.github.com/lifo/docrails/rails-api-documentation-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).
