Orphaned Rdoc for AR::Validations::ClassMethods::validate

I was scanning through active_record/validations.rb the other day and noticed that there's a method RDoc comment about ClassMethods::validate (which also addresses the validate_on_create and validate_on_update class methods) floating in space just north of validates_each. Since it's not stuck to a method def, RDoc ignores it.

(I did a bisect and found that the comment got orphaned back in January when ActiveSupport::Callbacks was extracted (http://github.com/rails/rails/commit/aae37bb4f7edd6a1820e420a60560369c6064f33).)

Does anyone have a better suggestion than converting that into a section in the module-level Rdoc for ActiveRecord::Validations::ClassMethods? As far as I know, RDoc's support for metaprogrammed methods (excluding the special case of attribute readers and writers) is non-existent.

Thanks. -hume.

Feel free to put the rdoc where you feel it makes sense.

Rails does heavy use of Ruby dynamic features and there's a mismatch with rdoc we need to cope with applying common sense. I believe a sensible driver is "if I was looking for this in the online API where would I expect it to be?"

For example the implementation of #save is scattered in several files. My interpretation is that the split is just done for modularity, it is a way to organize the implementation via separation of concerns. I guess it is not, say, a way to make some stuff like transactions optional.

Thus, in my recent revision of the #save rdocs I just assumed transactions, callbacks, and validations belong to the user interface and documented them in a place where they do not yet exist, which is AR::Base#save. In this case I chose that place because it is what you read if you click on "save" in the API docs.

If you want to submit that doc patch through docrails just contact Pratik.