Google Groups

Re: [Rails-docs] Re: api.rubyonrails.org is a ghetto


Xavier Noria Jun 8, 2011 3:04 PM
Posted in group: Ruby on Rails: Documentation
On Wed, Jun 8, 2011 at 10:28 PM, Loren Segal <lse...@soen.ca> wrote:

Hi Loren, thanks for joining the thread :).

> On Jun 4, 11:06 am, Xavier Noria <f...@hashref.com> wrote:
>> I'd like to move this forward for 3.2.
>>
>> For me the choice of YARD vs RDoc basically goes down to: if someone implements a doc generator based on source execution and introspection in tool T, then T wins.
>
> What do you mean by "source execution and introspection", exactly?
> YARD already has more powerful support for documenting metaprogrammed
> methods, but doesn't use "source execution" to do so. I'm not sure
> it's necessary to eval the codebase to document it. In the end, it
> doesn't *really* make things easier. The "eval" approach to generating
> docs has actually been looked at pretty thoroughly when architecting
> YARD-- we found that in practice you don't actually gain very much
> that can't be done with standard source parsing. If you can list
> specific examples of where YARD's support for metaprogrammed code is
> not sufficient, I'll be glad to look at them and make some concrete
> suggestions on how those situations can be dealt with.

Let me put an example: the Rails API should give the user a clear idea
of the methods a model responds to. Today it offers this raquitic

     http://api.rubyonrails.org/classes/ActiveRecord/Base.html

Where is #valid? Missing. As a user of Active Record I want to be able
to open the API of AR::Base and find #valid? and everything there.

We should rather provide something closer to this:

     http://reflexive-demo.heroku.com/reflexive/constants/ActiveRecord::Base

with better usability (and that's a problem to solve in the design).

In my view, a project like Rails has so much separation between its
internal organization and its public interface, that I think executing
and introspecting is the most effective approach to building its API:

    1. executing the source tree except for a list of exceptions is easy
    2. inspecting classes and modules with introspection is easy
    3. we get something much more comprehensive

This might not be the best approach for a generic documentation tool,
but I think it is the best approach for a project like Rails.

The user does not care about the internal organization of the code.
The user does not care about InstanceMethods and ClassMethods. The
user cares about what's the API available for a given class, and we do
not have a good answer to that as of today.

So, in particular, I want all the Ruby hooks like included or
inherited run, all the AS::Concern side-effects in place (AS::Concern
is used in more than a hundred places), I want

    MODULES.each do |mod|
      include mod
    end

in AC::Base to be executed. And we could start looking at the Rails
source code and list more and more examples.

The result won't be perfect, of course, but 1 and 2 are so *trivial in
comparison to a parser*, and you get so much better content to build
your docs from for such a cheap price, that for me this approach _for
Rails_ is a no-brainer (modulus it has not been implemented, it will
have its own issues I am sure.)

A parser would still be needed to extract doc strings, so the tool I
have in mind mixes both things.


>> If T is YARD, adopting it wouldn't imply necessarily we also adopt annotations. That would be a different discussion.
>
> I think the annotation discussion is inherently integral in adopting
> YARD; it should at least be mentioned here in brief.

Thanks for these thoughts on annotations. This is a topic where I have
not yet an actual opinion, only a priori mixed feelings (let me not
elaborate now). So I am personally open to this and interested in
discussing it.

But if you don't mind I'd like first to focus on the problem above,
because I see it as key for the evolution of the Rails API, and its
implementation, if it ever happens, may indirectly select a tool (or
create a new one).

I am considering sdoc as a very easy way to add the number one
requested feature, which is search. It has also a nice template. If
you are using RDoc, I think sdoc is really nice.

But integrating sdoc is very transparent. In particular, if we switch
to YARD someday and it has search by then, the fact that the API uses
sdoc won't be an obstacle. We are essentially at the same distance
from YARD + search today than today + sdoc.