As I mentioned earlier today, there some ideas to take the API to a
next level. I think Ruby on Rails is a fucking awesome software, and
it should have a fucking awesome API.
Yehuda is working on a different way to organize content. Rizwan Reza
is exploring the idea of supporting user comments, there was also a
guy in Baltimore that volunteered to have a look into that.
But there are also other ideas that I think are interesting at least
to be investigated, if any of you want to work on any of them that
would be totally great!
First of all an axiom:
It is OK that we build our own doc tool ad-hoc for Rails,
Four existing ideas, they may conflict with each other but we will
sort it out if the case arrives:
== User-Centered API
Most of the modularity in the Rails code base is there by design. But
an end-user does not really care whether AC::Base has been broken in
these many modules. If you go to AC::Base you should have all the
public interface right there.
Accomplishing this is difficult with parsing, since there are
inherited hooks going on, autoloads, code like
MODULES.each do |mod|
etc. The wild idea is to go and load recursively all the Rails lib
directories (except perhaps for a few exceptions with side-effects).
With all Rails libs executed, all hooks executed, etc. introspect in
memory, and build meaningful docs. You can delegate docstring
extraction to an existing parser.
== Linking Tests to the API
The API should be written in English, but sometimes it would be handy
to be able to consult right there the tests for a given method. You
know, a block with tests that is hidden by default, akin to the
current code block.
Here you need to investigate a way to link tests and methods, and be
able to insert them in the API.
== Testing Rails Guides
Rails Guides are really really great, but they need to be maintained.
If they had code coverage that would be included with the Rails test
suite and people would be aware of content being outdated by a patch.
That would help a lot, and hey, having tested documentation isn't an
exciting idea by itself? Yehuda, José, and Sam Ruby have done stuff in
that line for books (with different approximations). If you'd like to
take a stab at this it would be a good idea to have at least a look at
== Awesome Theme
This depends heavily on the rest, but anyway it is very important. For
the API to be fucking awesome, it has to *look* fucking awesome. The
idea here is to have a gorgeous theme, possibly based on the color
palette and overall style of Rails Guides, and Rails Contributors for