[DOCS] Improve Documentation for ActiveRecord's order Method [ci-skip]

[ChaelCodes]

Summary

Added documentation around the order method and what the acceptable parameters are. Strings have some interesting functionality where they raise an error if anything more complicated than a column name or function wrapping a column are passed. This wasn't documented, so let's fix that!

Other Information

Old	New

[jonathanhefner]

Thank you for working on this! 😃

[jonathanhefner]

Suggested change

	# column names and simple function(column_name) expressions with optional
	# ASC/DESC modifiers are allowed.
	# column names and simple <code>function(column_name)</code> expressions
	# with optional +ASC+/+DESC+ modifiers are allowed.

Also, what do you think about moving this paragraph up above the code examples?

[ChaelCodes]

I thought this location transitioned nicely to Arel, and meant they had an understanding of what string values passed to order looked like, before adding the complication of when to use Arel, but I'm fine with moving it up to the first description.

[ChaelCodes]

Updated to reflect all code review comments, and rebased to drop the commit "fix spelling of management in the changelog", because main is now fixed.

[jonathanhefner]

One more thing. Then, when you are happy with the changes, would you mind squashing the commits?

[jonathanhefner]

Sorry, this is my fault -- this needs to be

Suggested change

	# Applies an +ORDER BY+ clause to a query.
	# Applies an <code>ORDER BY</code> clause to a query.

Because of the space:

> require "rdoc"
> RDoc::Markup::ToHtml.new(RDoc::Options.new).convert("+ORDER BY+ vs +ORDERBY+")
=> "\n<p>+ORDER BY+ vs <code>ORDERBY</code></p>\n"

[p8]

Looking at some similar methods in this file, I'm not sure we should use ORDER BY here.
None of the other examples are using SQL in the description.

It also seems we use mostly relation instead of query.
This makes sense I guess, because a relation is returned.

reverse_order
https://github.com/rails/rails/blob/8807b93841ddd1a7fa2b2f44f02e1f690f3d9cc9/activerecord/lib/active_record/relation/query_methods.rb#L1151
reorder
https://github.com/rails/rails/blob/8807b93841ddd1a7fa2b2f44f02e1f690f3d9cc9/activerecord/lib/active_record/relation/query_methods.rb#L440
limit
https://github.com/rails/rails/blob/8807b93841ddd1a7fa2b2f44f02e1f690f3d9cc9/activerecord/lib/active_record/relation/query_methods.rb#L876
Where
https://github.com/rails/rails/blob/8807b93841ddd1a7fa2b2f44f02e1f690f3d9cc9/activerecord/lib/active_record/relation/query_methods.rb#L590-L591

Any objections if we change it to:

Suggested change

	# Applies an +ORDER BY+ clause to a query.
	# Applies an order clause to the relation.

Or maybe, since multiple orders can be added:

Suggested change

	# Applies an +ORDER BY+ clause to a query.
	# Adds an order clause to the relation.

Sorry for the bikeshed 🙇

[jonathanhefner]

Looking at some similar methods in this file, I'm not sure we should use ORDER BY here.
None of the other examples are using SQL in the description.

There are a few that do:

rails/activerecord/lib/active_record/relation/query_methods.rb

Lines 20 to 21 in 4b4895e

	# Returns a new relation expressing WHERE + NOT condition according to
	# the conditions in the arguments.

rails/activerecord/lib/active_record/relation/query_methods.rb

Line 185 in 4b4895e

# Forces eager loading by performing a LEFT OUTER JOIN on +args+:

rails/activerecord/lib/active_record/relation/query_methods.rb

Lines 258 to 259 in 4b4895e

	# Second: Modifies the SELECT statement for the query so that only certain
	# fields are retrieved:

rails/activerecord/lib/active_record/relation/query_methods.rb

Lines 390 to 391 in 4b4895e

	# Allows to specify an order by a specific set of values. Depending on your
	# adapter this will either use a CASE statement or a built-in function.

rails/activerecord/lib/active_record/relation/query_methods.rb

Lines 830 to 831 in 4b4895e

	# Allows to specify a HAVING clause. Note that you can't use HAVING
	# without also specifying a GROUP clause.

That said, I don't have a strong preference. 😄

[p8]

Indeed 👍. I’ll leave it up to @ChaelCodes

[ChaelCodes]

I think including the ORDER BY provides more information than just saying order but I'm 50/50 on query vs relation, so I'll replace it with relation next time I'm at my computer.

[p8]

If we are sticking with the ORDER BY I guess it makes sense to also stick with query 🙂 .

[ChaelCodes]

Squashed!

[p8]

Thanks @ChaelCodes ! This looks ready to go for me.. 🚢 🙌
Could you squash commits again?
I guess @jonathanhefner already approved?

[ChaelCodes]

@p8 squashed and building. Sorry for the short message, it's early here.

[p8]

@ChaelCodes no worries 😄 . Thanks for the quick replies!

[jonathanhefner]

Ack, I noticed +function(column_name)+ didn't get changed to <code>function(column_name)</code> (per #43018 (comment)). Since we've already done multiple iterations, I did a quick force push to fix it. I hope you don't mind, @ChaelCodes. 🙏

Thank you again, @ChaelCodes! And thank you, @p8, for reviewing!