From: Phrogz Date: 2007-08-15T03:35:01+09:00 Subject: Re: Can ri distinguish core methods from 3rd party methods? [was: Non Existent Method Dir.empty? Description via "ri"] On Aug 14, 11:54 am, Daniel Berger wrote: > On Aug 14, 11:33 am, "Wolfgang N�dasi-donner" > 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.