While the *content* of the API has improved vastly since docrails was
created (and content is key), and guides have provided a previously
non-existent top-down introduction to how to use things, I agree that
the API is not on par with the framework, and wrote an email about
that some months ago suggesting different ways this could be improved:
"Taking the API to the next level"
http://groups.google.com/group/rubyonrails-core/browse_thread/thread/d8187a0de0e10312/554fc910fb77c178
The template has changed in Rails 3 only to match the color palette of
guides, which is the one theme theme being pursued.
The API needs a better template, and needs a search box. There was
some work being done in that direction that never saw the light of the
day (guess it didn't finish). But I have not pushed too hard there
because I think the solution is not only a better template. That's not
enough.
I am totally convinced we need to create a new API generation tool,
perhaps ad-hoc for Rails, perhaps based on YARD I don't know, that
evaluates the entire source tree with some exceptions. We need to have
all the concerns executed, and as much dynamic stuff as possible.
As a user, I want to go to AR::Base and see the API of a model, I
don't give a shit about the internal organization and partitioning in
a myriad modules of its API. It is OK to mention them: "this method is
defined in module M", but I want it there in AR::Base. And same thing
for everything.
So, execute the tree, and introspect as reflexive does
(https://github.com/dolzenko/reflexive). Use a static parser to
extract the doc snippets per method or whatever, and mix them
together.
That would be a real improvement.
Regarding YARD annotations... I am personally not convinced about
them. On one hand they emphasize types to the writer and programmer,
while Ruby is about being able to respond to methods (I know you can
express duck typing with them). I have mixed feelings about putting
types so prominently everywhere. On the other hand, I am afraid that
in practice they may give place to too terse APIs.
But anyway, for me this is not RDoc vs YARD, this is about doing
bringing the documentation to the next level, and that means more
profound changes from my point of view.
I am +1 on this. YARD is currently intensively developed, so we can expect even more profit moving from Rails API to YARD.Any news on topic?
--
You received this message because you are subscribed to the Google Groups "Ruby on Rails: Documentation" group.
To view this discussion on the web visit https://groups.google.com/d/msg/rubyonrails-docs/-/SWRpWVpqd3BMaFlK.
To post to this group, send email to rubyonra...@googlegroups.com.
To unsubscribe from this group, send email to rubyonrails-do...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/rubyonrails-docs?hl=en.
> I'm ok with yard, but if sdoc provides both a nice template and searching
> without a lot of change, that sounds good, too.
> I also want to mention railsapi.com. I use it more than the official API
> site because of its textmate-like searchbox. For example typing "acm" will
> quickly narrow down the list to activemodel, actionmailer, etc. Any idea if
> sdoc allows searching like that?
railsapi.com is generated with sdoc :)
--
You received this message because you are subscribed to the Google Groups "Ruby on Rails: Documentation" group.
To view this discussion on the web visit https://groups.google.com/d/msg/rubyonrails-docs/-/R2FCM2phUmRrSFFK.
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.
Oh yes, extracting docstrings and source code is hard. I didn't
emphasize that because existing tools solve it and in my view the most
natural thing to try first is to inject an alternative ancestry chain
into RDoc or YARD somehow before generation.
For example, would it be technically possible to have a YARD after
hook that performs the evaluation of the source tree, rewrites
ancestries in YARD's database according to the ones available at
runtime via introspection, and then lets YARD continue?
> On Jun 9, 3:21 am, Xavier Noria <f...@hashref.com> wrote:
>> For example, would it be technically possible to have a YARD after
>> hook that performs the evaluation of the source tree, rewrites
>> ancestries in YARD's database according to the ones available at
>> runtime via introspection, and then lets YARD continue?
>
> Yes-- the example above does this, at least for AC::Base.
That's good news :).
> As I said,
> this is something you should use in isolated cases, since, in most
> cases YARD does it right the first time.
But do you realize that a lot of includes/extends are implicit/dynamic
and happen when the class definition is executed? There's no way a
parser can build an ancestor chain for most Rails classes that matches
the one in runtime, notably for the most important ones. For starters
there are more than one hundred uses of AS::Concern.
> You can handle each isolated
> case as it comes up.
Well, we differ in that approach, though that is not important. The
number of cases to catch is so numerous and variable over the
evolution of the project that executing everything except for a list
of files maintained by hand seems more robust to me. Does YARD care if
the after hook rewrites most of the ancestry chain in its database?
Can it break something?
> Also, I realized the example needs one minor modification:
> "Parser::SourceParser" instead of just SourceParser. Also you may not
> be able to just require 'action_controller/base', you might have to
> pull in more of Rails. I tested the above example out myself but
> parsed out the constant value text manually (rather than evaling
> runtime stuff) and got the output you were looking for.
OK, I will definitely investigate this path. Looks really
cost-effective and promising.
On Wednesday, 10 August 2011 at 5:36 PM, Eugene Pirogov wrote:
So it's two months since the last message here. Any progress on this? Is Rails core team still against the migration to YARDoc?
--
You received this message because you are subscribed to the Google Groups "Ruby on Rails: Documentation" group.
To view this discussion on the web visit https://groups.google.com/d/msg/rubyonrails-docs/-/mtfUoaZB22kJ.
> So it's two months since the last message here. Any progress on this?
Yes, there's progress, if everything goes as planned the API of 3.1
will be published with a revised sdoc.
As I have expressed in the thread, I am personally NOT against YARD.
It is an option in the radar, not discarded or anything. But I am
neither in favor of switching the Rails docs to YARD as of today.
I've thought about this, and for me the next logical step in the
evolution of the API is sdoc. All the code base is ready, we get a
much nicer design, better navigation, and a static site with a search
box that does a very useful fuzzy search. A search box is the number
one missing feature of the API. I really like what sdoc provides.
That's going to be a really nice step forward for end users given the
API has been stagnant for years (except for content).
That's for me the most sensible next step. Regarding the future, I
don't really know, time will say.
Still can't stop dreaming that Rails one day will migrate to YARD. Any chances to see yardified rails docs in 4.0?