On Aug 14, 11:54 am, Daniel Berger <djber... / gmail.com> wrote:
> On Aug 14, 11:33 am, "Wolfgang N?dasi-donner" <ed.oda... / wonado.de>
> wrote:

> > Unfortunately it is not visible in the ri output where the method comes
> > from.
>
> That's an excellent point Wolfgang. There ought to be a way within ri
> for a user to distinguish between a core method and a method added on
> by a 3rd party library. I haven't double checked the ri options, but I
> don't think there's a way.
>
> If not, we should probably discuss (here or on ruby-core) if it's
> feasible and, if so, what the output should look like.
>
> Or, we could collectively decide that, when modifying core classes, we
> should stick a tag of some sort on the method doc itself, either so
> that it shows up literally in the output, or something rdoc can latch
> onto. For example, the actual comments look like this:
>
> # Returns whether or not +path+ is empty.  Returns false if +path+
> # is not a directory, or contains any files other than '.' or '..'.
> #
> def self.empty?(path)
>    ...
> end
>
> Perhaps I should add this at the bottom of each comment?
>
> # library: win32-dir
>
> Dunno. What do people think?

I think that's a hack solution to the problem. It might be a good idea
since getting rdoc/ri fixed will take a lot of time, but the proper
solution is as you say: We need rdoc and ri to be fixed to properly
note what file/library a method was defined (and redefined) in.

I'm not (yet) volunteering to do any of the spec or implementation
work for this, but I'm on the verge. Proper documentation is a near
passion of mine, and although my latest solution (years old now -
http://phrogz.net/ObjJob/) doesn't address this particular concern, I
would love to see and/or do some serious work to make auto-generated
documentation:
  * Include information on what file you need to add
  * Optionally show/hide inherited methods
  * Optionally list 'attributes' among methods
  * Handle method redefinitions, including documentation from both.

I'm quite disturbed that (last time I checked) http://www.ruby-doc.org/core
includes classes modules and methods from stdlib. Clearly that
shouldn't be the case (right), and is related to this.