Re: Why Class decls and API docs don't Match

From: [email protected] [mailto:[email protected]]

Anybody who’s done any Ruby on Rails will have seen, edited, or
constructed the following which is suggestive of a general Ruby issue:

[snip]

a) You might want to post this rant/question to the rails mailing list
instead of the Ruby mailing list for more appropriate exposure.

b) Your problem/question seems not to be the fact that the rails
documentation, or the tool that rails uses to generate its
documentation, does not include information you want to see, right?

This is a tricky nut to crack. ActionController::Layout is included in
ActionController::Base in action_controller.rb like this:

ActionController::Base.class_eval do
include ActionController::Flash
include ActionController::Filters
include ActionController::Layout
include ActionController::Benchmarking
[…snip…]
end

RDoc currently doesn’t see that as an include, I suppose because it
can’t figure out where it goes.

More constructively, you might say:
“Hey, I wish RDoc was able to figure out crazy metaprogramming for
proper inheritance”
or
“Hey, I wish someone could modify RDoc so that we could tell it things
to document that it can’t figure out for itself”
or
“Hey, I wish someone would fix the rails docs for me…auto-generation
isn’t doing it for me.”

b) Your problem/question seems not to be the fact that the rails
documentation, or the tool that rails uses to generate its
documentation, does not include information you want to see, right?
Yes. But not on purpose. The the thrust of my question was:
If this code is unambigous:

class ApplicationController < ActionController::Base
layout “standard”
end

Then how come layout can’t be found can’t be found in
ActionController::Base?
For in all C++/java/Eiffel languages layout() would be a method in
ActionController::Base
or its superclasses. Period.

Now I understand that rdoc comes with a story as to why it doesn’t
include layout.
And, really, that’s fine.

But it still leaves open the question: what method would show that? For
on a complex library like Rails programmers can’t be spending their
time trying to figure out what objects can call or manually inspecting
obj.inspect or whatever …

This is a tricky nut to crack. ActionController::Layout is included in
ActionController::Base in action_controller.rb like this:
Yes, I belatedly found that the right thing to do and would have
largely answered my question.
See my other post.

Gavin K. wrote:

a) You might want to post this rant/question to the rails mailing list
instead of the Ruby mailing list for more appropriate exposure.
This issue pertains to Ruby not Rails. And, in my opinion, it’s a
fundamental issue.
rdoc is a program which runs on any Ruby source.

You can’t have a system in which, despite MBs of fancy-smancy HTML API
docs,
you only know what you know because you spent the minutes (hours, days)
playing
around in the source code to see what’s what. Ruby – the language –
needs to do
better here.

On 10/19/06, [email protected] [email protected] wrote:

Then how come layout can’t be found can’t be found in
ActionController::Base?
For in all C++/java/Eiffel languages layout() would be a method in
ActionController::Base
or its superclasses. Period.

I can see your point.

The problem here is that Ruby is a dynamic language. You cannot be
sure what ends up where, unlike in C++/Java. RDoc catches (or at least
tries to catch) those includes that occur within the class definition.
Catching those that happen halfway through the program isn’t that
easy. The case with class method is exactly this case - the inclusion
is triggered by calling extend ActionController::Layout::ClassMethods
on AC::Base in AC::L::CM.included callback that is called by include
AC::L in AC::B. You see it’s pretty indirect.

Still you have script/console, that allows you to ask AC::B about its
methods.

Disagreed. This has nothing to do with Ruby the language! RDoc is a
tool that tries to parse the language statically. It is not part of the
core of Ruby.
Having a conversation about whether the issue lies with RDOC or RUBY is
not the conversation I want to have. Because even if resolved … even
if a judgement as to what’s culpable was assigned with large agreement,
the issue remains unsolved.

As to implementation, perhaps RDOC could have been made better. I
concede that. Perhaps the right place to begin is the explicit
inclusion of includes, and requires statments in all API docs. At least
for ActionController::Base, one of the zillion Ruby classes out there,
it doesn’t list includes and requires. Second, RDOC shoud process the
class_eval construction as in: ActionController::Base.class_eval do
… end. And third, perhaps RDOC should exhaustively process all files
under some root ``R". I write that because had RDOC processed

/usr/local/lib/ruby/gems/1.8/gems/actionpack-1.12.5/lib/action_controller.rb

perhaps the existing RDOC would have generated more complete API docs.
I’d have to check how the GEM RDOC generation is done to know whether
or not it even attempted to process this file. And finally, perhaps
RDOC should generate two lists: a list of modules and a list of classes
where the classes are show all their methods depending on their super
classes and modules where included.

But on the other hand, implementation was always going to be a
fundamental challenge precisely because Ruby isn’t a static language as
you write. Indeed, because of the PERL like flexibility in
the syntax and the number of ways modules and classes can be expanded
— all issues about
the language itself — it’d be a real challenge to get a good RDOC
implementation running. By and large, these aren’t the issues you’d run
into with Eiffel/Java/C++ precisely because they’re static. Eiffel, in
particular, goes out of its way to have a minimal PASCAL like syntax.
In terms of implementing something, that would make the job easier.

As such, Ruby designers might have more carefully considered how’d
they expect programmers
to understand Ruby libraries for that’s how Ruby development of Ruby
programs would proceed.
In asking this question via IRC, a programmer responded that Ruby
libraries are complex thereby
requiring all those modules etc. and that this creates additional
difficulties in documenting what
the libraries do. In fact that’s no kind of answer. It’s a plattitude.
Almost all engineering problems
are complex and difficult. Managing complexity is everybody’s problem.

I will stop here. I don’t want to say more or less. I don’t want to
start discussing dynamic v.
static typed languages either. All I have done is identify a single
area of Ruby which requires
some continuous improvement. In working with Ruby and Rails for about
one week in some
detail, this is the only serious qualm I have.

On Oct 19, 2006, at 1:55 PM, [email protected] wrote:

Second, RDOC shoud process the
class_eval construction as in: ActionController::Base.class_eval do
… end.

If RDoc ran the code it parsed, then it would open a security hole a
mile wide, as I could then run arbitrary code on the machines of
anyone producing documentation. That’s why I chose not to do this.

Regards

Dave T.

[email protected] wrote:

You can’t have a system in which, despite MBs of fancy-smancy HTML API
docs, you only know what you know because you spent the minutes (hours, days)
playing around in the source code to see what’s what.

Agreed.

Ruby – the language – needs to do better here.

Disagreed. This has nothing to do with Ruby the language! RDoc is a
tool that tries to parse the language statically. It is not part of the
core of Ruby.

The only way Ruby the language could do better for what you want, I
think, would be to change into a system where everything about the
runtime state of the system could be determined at ‘compile’ time
without running the code.

How do you think that Ruby the language should do better?

If RDoc ran the code it parsed, then it would open a security hole a
mile wide, as I could then run arbitrary code on the machines of
anyone producing documentation. That’s why I chose not to do this.
Perhaps.

But why do that? One only need to parse for the purpose of extracting
documentation.

On 10/20/06, [email protected] [email protected] wrote:

If RDoc ran the code it parsed, then it would open a security hole a
mile wide, as I could then run arbitrary code on the machines of
anyone producing documentation. That’s why I chose not to do this.
Perhaps.

But why do that? One only need to parse for the purpose of extracting
documentation.

As I think of it, one solution could be that doc writers would hint
RDoc about the included modules, if it cannot discover them itself.
Something like

:class_extend: ActiveController::Layout::ClassMethods