search

lsegal / yard

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

YARDoc'ing ActiveModel stuff #339

Closed rurounijones closed 13 years ago

rurounijones commented 13 years ago

Hello all,

Given that 0.7 has some interesting new macro stuff is there a suggested best practice for documenting things like validations, associations, callbacks etc. that are found in your average Rails ActiveModel derived class?

Useful for documenting things like murderous validations with regexps in plain english etc.

lsegal commented 13 years ago

The new DSL detection (and macro) behaviour in 0.7 is mostly meant to auto-generate method/attribute object documentation. I'm not entirely sure validations, associations and callbacks can be translated into these method/attribute objects, because they're not really defined by any API method on the class.

I would say that, in general, the better way to handle these kinds of elements is still via plugin. That said, you could hack it with macros by creating "fake" method objects on the class. See @ryansobol's feature request #332 for his use case (and my suggestions), which is actually quite similar to what you'd want to do.

rurounijones commented 13 years ago

Thanks for the information. I thought that might be the case but wanted to make sure before looking into creating a plugin (As no ActiveModel plugins exist at the moment as far as I can tell.)