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

1 files changed, 8 insertions, 1 deletions

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.