search

lsegal / yard

YARD is a Ruby Documentation tool. The Y stands for "Yay!"
http://yardoc.org
MIT License
1.95k stars 398 forks source link

Supporting CodeObject hierarchies of other languages #544

Closed arthurschreiber closed 12 years ago

arthurschreiber commented 12 years ago

Hello Loren,

I'm currently looking at creating a Yard Plugin to document Tcl files, and have been running into some small limitations.

(You can take a look at it at arthurschreiber/yard-tcl, but right now it's mostly a hack.)

The "problem" I've ran into that yard's CodeObject hierarchy is currently completely linked with Ruby. That is in contrast to the parser and handler functionality, which is completely language agnostic. For generating Tcl documentation, that is kind of a problem, as I have objects that don't cleanly map to ruby types.

Now, I could go ahead and create a separate hierarchy of CodeObjects starting from YARD::CodeObjects::Base that fit the Tcl language better, but currently YARD::CodeObjects::Base contains a lot of Ruby specifics.

Additionally, the use of YARD::CodeObjects::RootObject is hardcoded in YARD::RegistryStore, so I can't even have my own Tcl specific Root Object without monkey patching YARD internals.

Do you have plans on changing these pain points? Or, alternatively, what would you suggest to be changed and how, so I can code up a patch. :)

lsegal commented 12 years ago

Hi Arthur,

On 5/14/2012 3:35 PM, Arthur Schreiber wrote:

Hello Loren,

I'm currently looking at creating a Yard Plugin to document Tcl files, and have been running into some small limitations.

(You can see take a look at it at arthurschreiber/yard-tcl, but right now it's mostly a hack.)

Cool! Will check it out.

The "problem" I've ran into that yard's CodeObject hierarchy is currently completely linked with Ruby. That is in contrast to the parser and handler functionality, which is completely language agnostic. For generating Tcl documentation, that is kind of a problem, as I have objects that don't cleanly map to ruby types.

The CodeObjects hierarchy should handle this. It should also be language agnostic. It was designed this way.

Now, I could go ahead and create a separate hierarchy of CodeObjects starting from YARD::CodeObjects::Base that fit the Tcl language better, but currently YARD::CodeObjects::Base contains a lot of Ruby specifics.

Do you have an example of something Ruby specific in the Base class? The only place where "Ruby" shows up anywhere besides in documentation is for the "source_type" default. The source_type attribute exists specifically to specify different languages.

Additionally, the use of YARD::CodeObjects::RootObject is hardcoded in YARD::RegistryStore, so I can't even have my own Tcl specific Root Object without monkey patching YARD internals.

There is nothing Ruby specific about the RootObject. It is simply the "root node" of the tree that contains a list of children objects. The child objects can represent anything. You shouldn't need a "TCL specific" root node.

Maybe you are getting confused by the wording of the documentation. The docs describe the application of the objects to the Ruby world, because that's what YARD primarily is used for. Even the Parser/Handlers architectures mention Ruby specific things at least a few times, since this is the primary audience. You can every time you see Ruby, though. The documentation for classes isn't expressing a contract that the classes be specifically used for Ruby types. Even a "MethodObject" is not Ruby specific, and can represent methods in any language that has "methods" (you would still subclass to change the "sep" method and certain other language specific details, though).

Note that I've pushed this to the mailing list since that's where this kind of discussion belongs: yardoc@googlegroups.com

Loren