Rework synonym, synonym_for documentation

The map_column example was incorrect, and overall the purpose
of this parameter as well as that of synonym_for was not explained;
examples added along with more encouragement to use hybrids.

Change-Id: I20bd286f541f798daa81fa598c0f31db1f5aa6ed

1 files changed, 26 insertions, 11 deletions

diff --git a/lib/sqlalchemy/ext/declarative/api.py b/lib/sqlalchemy/ext/declarative/api.py
index 5f9ffac2b..77a03bc4a 100644
--- a/lib/sqlalchemy/ext/declarative/api.py
+++ b/lib/sqlalchemy/ext/declarative/api.py
@@ -69,21 +69,36 @@ class DeclarativeMeta(type):
 
 
 def synonym_for(name, map_column=False):
-    """Decorator, make a Python @property a query synonym for a column.
+    """Decorator that produces an :func:`.orm.synonym` attribute in conjunction
+    with a Python descriptor.
 
-    A decorator version of :func:`~sqlalchemy.orm.synonym`. The function being
-    decorated is the 'descriptor', otherwise passes its arguments through to
-    synonym()::
+    The function being decorated is passed to :func:`.orm.synonym` as the
+    :paramref:`.orm.synonym.descriptor` parameter::
 
-      @synonym_for('col')
-      @property
-      def prop(self):
-          return 'special sauce'
+        class MyClass(Base):
+            __tablename__ = 'my_table'
+
+            id = Column(Integer, primary_key=True)
+            _job_status = Column("job_status", String(50))
+
+            @synonym_for("job_status")
+            @property
+            def job_status(self):
+                return "Status: %s" % self._job_status
+
+    The :ref:`hybrid properties <mapper_hybrids>` feature of SQLAlchemy
+    is typically preferred instead of synonyms, which is a more legacy
+    feature.
+
+    .. seealso::
+
+        :ref:`synonyms` - Overview of synonyms
 
-    The regular ``synonym()`` is also usable directly in a declarative setting
-    and may be convenient for read/write properties::
+        :func:`.orm.synonym` - the mapper-level function
 
-      prop = synonym('col', descriptor=property(_read_prop, _write_prop))
+        :ref:`mapper_hybrids` - The Hybrid Attribute extension provides an
+        updated approach to augmenting attribute behavior more flexibly than
+        can be achieved with synonyms.
 
     """
     def decorate(fn):