Undocumented ActiveRecord bang methods

Question

Is there a reason why ActiveRecord's bang methods are public, but not documented nor mentioned anywhere?

For example, where!, order!, limit! and others are all public and used by their non-bang counterparts.

I understand that they change the query object instead of its clone (and caution is necessary), but so do other bang methods, which are usually very well-documented.

Answer 1

They want to keep the API to be immutable, see the comments on this commit:

https://github.com/rails/rails/commit/8c2c60511beaad05a218e73c4918ab89fb1804f0

And as for all undocumented methods (with # :nodoc:), they are part of the private API. You should not use them as they could be removed without a warning.

hth