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

**URL:** <https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72950>\
**Category:** Ruby\
**Created:** [October 20, 2006, 1:22am UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72950 "2006-10-20T01:22:02Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**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:22am UTC](https://www.ruby-forum.com/t/re-why-class-decls-and-api-docs-dont-match/72950/1 "2006-10-20T01:22:02Z")

</div>

From: removed\_email\_address@domain.invalid [[mailto:removed\_email\_address@domain.invalid](mailto:removed_email_address@domain.invalid)]

> > 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.

class Foo  
include Object.const\_get( gets.chomp )  
end

That’s an extreme case, but one in which it is impossible to know via  
parsing what module will be brought into the class.

Some slightly less absurd cases:

class Foo  
if rand \> 0.1  
include SuperExplodingFun  
end  
end

FASHIONABLE\_MODULE\_OF\_THE\_WEEK = Enumerable  
class Foo  
include FASHIONABLE\_MODULE\_OF\_THE\_WEEK  
end

class Object  
def self.get\_all\_the\_standard\_stuff  
include Enumerable  
include MySexyModule::HotStuff  
end  
end

class Foo  
get\_all\_the\_standard\_stuff  
end

That last example is somewhat like what the Rails case that started all  
this does - there’s some code that indirectly pulls in the module. RDoc  
can’t know this without running the code, and the author of RDoc made  
the choice not to run the code.

(And even if it did run the code, there are theoretically certain  
non-deterministic cases like the first two I posted which it could never  
handle in an automated way.)