improved deprecation

Author: andrewelamb

synapseutils/sync.py

@@ -1133,11 +1133,6 @@ def syncToSynapse(
 ) -> None:
     """Synchronizes files specified in the manifest file to Synapse.
 
-    .. deprecated:: 4.13.0
-        Use :meth:`synapseclient.models.Project.sync_to_synapse` or
-        :meth:`synapseclient.models.Folder.sync_to_synapse` instead.
-        This function will be removed in v5.0.0.
-
     Given a file describing all of the uploads, this uploads the content to Synapse and
     optionally notifies you via Synapse messagging (email) at specific intervals, on
     errors and on completion.
@@ -1177,6 +1172,21 @@ def syncToSynapse(
 
     Returns:
         None
+
+    Example: Migration to new method
+         
+
+        ```python
+        # Old approach (DEPRECATED)
+        # import synapseutils
+        # synapseutils.syncToSynapse(syn, manifestFile="path/to/manifest.tsv")
+
+        # New approach (RECOMMENDED)
+        from synapseclient.models import Project
+
+        project = Project(id="syn1234")
+        project.sync_to_synapse(manifest_path="path/to/manifest.csv")
+        ```
     """
     wrap_async_to_sync(
         coroutine=syncToSynapse_async(
@@ -1191,6 +1201,13 @@ def syncToSynapse(
     )
 
 
+@deprecated(
+    version="4.13.0",
+    reason=(
+        "To be removed in 5.0.0. Use Project.sync_to_synapse_async or "
+        "Folder.sync_to_synapse_async from synapseclient.models instead."
+    ),
+)
 async def syncToSynapse_async(
     syn: Synapse,
     manifestFile,
@@ -1200,7 +1217,68 @@ async def syncToSynapse_async(
     merge_existing_annotations: bool = True,
     associate_activity_to_new_version: bool = False,
 ) -> None:
-    """Async version of syncToSynapse."""
+    """Synchronizes files specified in the manifest file to Synapse.
+
+    .. deprecated:: 4.13.0
+        Use :meth:`synapseclient.models.Project.sync_to_synapse` or
+        :meth:`synapseclient.models.Folder.sync_to_synapse` instead.
+        This function will be removed in v5.0.0.
+
+    Given a file describing all of the uploads, this uploads the content to Synapse and
+    optionally notifies you via Synapse messaging (email) at specific intervals, on
+    errors and on completion.
+
+    [Read more about the manifest file format](../../explanations/manifest_tsv/)
+
+    There are a few conversions around annotations to call out here.
+
+    ## Conversion of annotations from the TSV file to Python native objects
+
+    The first annotation conversion is from the TSV file into a Python native object. For
+    example Pandas will read a TSV file and convert the string "True" into a boolean True,
+    however, Pandas will NOT convert our comma delimited and bracket wrapped list of
+    annotations into their Python native objects. This means that we need to do that
+    conversion here after splitting them apart.
+
+    ## Conversion of Python native objects for the REST API
+
+    The second annotation conversion occurs when we are taking the Python native objects
+    and converting them into a string that can be sent to the REST API. For example
+    the datetime objects which may have timezone information are converted to milliseconds
+    since epoch.
+
+    Arguments:
+        syn: A Synapse object with user's login, e.g. syn = synapseclient.login()
+        manifestFile: A tsv file with file locations and metadata to be pushed to Synapse.
+        dryRun: Performs validation without uploading if set to True.
+        sendMessages: Sends out messages on completion if set to True.
+        retries: Number of retries to attempt if an error occurs.
+        merge_existing_annotations: If True, will merge the annotations in the manifest
+            file with the existing annotations on Synapse. If False, will overwrite the
+            existing annotations on Synapse with the annotations in the manifest file.
+        associate_activity_to_new_version: If True, and a version update occurs, the
+            existing activity in Synapse will be associated with the new version. The
+            exception is if you are specifying new values to be used/executed, it will
+            create a new activity for the new version of the entity.
+
+    Returns:
+        None
+
+    Example: Migration to new method
+         
+
+        ```python
+        # Old approach (DEPRECATED)
+        # import synapseutils
+        # await synapseutils.syncToSynapse_async(syn, manifestFile="path/to/manifest.tsv")
+
+        # New approach (RECOMMENDED)
+        from synapseclient.models import Project
+
+        project = Project(id="syn1234")
+        await project.sync_to_synapse_async(manifest_path="path/to/manifest.csv")
+        ```
+    """
     df = await readManifestFile_async(syn, manifestFile)
 
     sizes = [