clarify order_by(None) for Core; improve wording

the order_by(None) convention was documented for orm.Query
but not Core select.

Change-Id: I0c1ad76c3eefba1cb54b1649cfd09169c17e2bba

2 files changed, 19 insertions, 4 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 83b299407..eab7a3d75 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1799,11 +1799,19 @@ class Query(
     @_generative
     @_assertions(_no_statement_condition, _no_limit_offset)
     def order_by(self, *clauses):
-        """Apply one or more ORDER BY criterion to the query and return
+        """Apply one or more ORDER BY criteria to the query and return
         the newly resulting :class:`_query.Query`.
 
-        All existing ORDER BY settings can be suppressed by  passing
-        ``None``.
+        e.g.::
+
+            q = session.query(Entity).order_by(Entity.id, Entity.name)
+
+        All existing ORDER BY criteria may be cancelled by passing
+        ``None`` by itself.  New ORDER BY criteria may then be added by
+        invoking :meth:`_orm.Query.order_by` again, e.g.::
+
+            # will erase all ORDER BY and ORDER BY new_col alone
+            q = q.order_by(None).order_by(new_col)
 
         .. seealso::
 
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index b0aaa5a31..aed648297 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -3781,12 +3781,19 @@ class GenerativeSelect(DeprecatedSelectBaseGenerations, SelectBase):
     @_generative
     def order_by(self, *clauses):
         r"""Return a new selectable with the given list of ORDER BY
-        criterion applied.
+        criteria applied.
 
         e.g.::
 
             stmt = select(table).order_by(table.c.id, table.c.name)
 
+        All existing ORDER BY criteria may be cancelled by passing
+        ``None`` by itself.  New ORDER BY criteria may then be added by
+        invoking :meth:`_sql.Select.order_by` again, e.g.::
+
+            # will erase all ORDER BY and ORDER BY new_col alone
+            stmt = stmt.order_by(None).order_by(new_col)
+
         :param \*clauses: a series of :class:`_expression.ColumnElement`
          constructs
          which will be used to generate an ORDER BY clause.