Rails core - Sep 2008 - 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.

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Core" group.
To post to this group, send email to rubyonrails-core@googlegroups.com
To unsubscribe from this group, send email to
rubyonrails-core+unsubscribe@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/rubyonrails-core?hl=en
-~----------~----~----~----~------~----~------~--~---

On Sat, Sep 6, 2008 at 6:27 PM, John D. Hume <duelin.markers@gmail.com>
wrote:
> 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.
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.

--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"Ruby on Rails: Core" group.
To post to this group, send email to rubyonrails-core@googlegroups.com
To unsubscribe from this group, send email to
rubyonrails-core+unsubscribe@googlegroups.com
For more options, visit this group at
http://groups.google.com/group/rubyonrails-core?hl=en
-~----------~----~----~----~------~----~------~--~---