# Re: Why Class decls and API docs don't Match **URL:** \ **Category:** Ruby\ **Created:** [October 19, 2006, 12:47am UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72798 "2006-10-19T00:47:48Z")\ **Posts on this page:** 9\ **Page:** 1
**Author:** ![phrogz](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/2acd7d/32.png) [@phrogz](https://www.ruby-forum.com/u/phrogz)\ **Post date:** [October 19, 2006, 12:47am UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72798/1 "2006-10-19T00:47:48Z")
From: removed\_email\_address@domain.invalid [[mailto:removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid)] > 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.” ---
**Author:** ![phrogz](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/2acd7d/32.png) [@phrogz](https://www.ruby-forum.com/u/phrogz)\ **Post date:** [October 19, 2006, 1:45am UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72798/2 "2006-10-19T01:45:54Z")
> 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. ---
**Author:** ![phrogz](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/2acd7d/32.png) [@phrogz](https://www.ruby-forum.com/u/phrogz)\ **Post date:** [October 19, 2006, 4:06pm UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72798/3 "2006-10-19T16:06:54Z")
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. ---
**Author:** ![phrogz](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/2acd7d/32.png) [@phrogz](https://www.ruby-forum.com/u/phrogz)\ **Post date:** [October 19, 2006, 4:41pm UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72798/4 "2006-10-19T16:41:55Z")
On 10/19/06, removed\_email\_address@domain.invalid [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) 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. ---
**Author:** ![phrogz](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/2acd7d/32.png) [@phrogz](https://www.ruby-forum.com/u/phrogz)\ **Post date:** [October 19, 2006, 8:56pm UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72798/5 "2006-10-19T20:56:20Z")
> 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. ---
**Author:** ![phrogz](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/2acd7d/32.png) [@phrogz](https://www.ruby-forum.com/u/phrogz)\ **Post date:** [October 19, 2006, 9:43pm UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72798/6 "2006-10-19T21:43:10Z")
On Oct 19, 2006, at 1:55 PM, removed\_email\_address@domain.invalid 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. ---
**Author:** ![phrogz](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/2acd7d/32.png) [@phrogz](https://www.ruby-forum.com/u/phrogz)\ **Post date:** [October 19, 2006, 4:51pm UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72798/7 "2006-10-19T16:51:56Z")
removed\_email\_address@domain.invalid 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? ---
**Author:** ![phrogz](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/2acd7d/32.png) [@phrogz](https://www.ruby-forum.com/u/phrogz)\ **Post date:** [October 20, 2006, 12:55am UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72798/8 "2006-10-20T00:55:59Z")
> 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. ---
**Author:** ![phrogz](https://www.ruby-forum.com/letter_avatar_proxy/v4/letter/p/2acd7d/32.png) [@phrogz](https://www.ruby-forum.com/u/phrogz)\ **Post date:** [October 20, 2006, 1:26am UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72798/9 "2006-10-20T01:26:02Z")
On 10/20/06, removed\_email\_address@domain.invalid [removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid) 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