update docstrings

Author: danlu1

synapseclient/models/mixins/storage_location_mixin.py

@@ -293,6 +293,12 @@ async def set_storage_location_async(
         To add a storage location without removing existing ones, first retrieve the
         current setting via `get_project_setting_async`, append to its `locations`
         list, and call `store_async` on the returned `ProjectSetting` directly.
+        The first ID in the list is the default upload destination.
+        To obtain a storage location ID, create a
+        [StorageLocation][synapseclient.models.StorageLocation] and use its
+        `storage_location_id`. See
+        [StorageLocationType][synapseclient.models.StorageLocationType] for the
+        available storage backend types.
 
         Arguments:
             storage_location_id: The storage location ID(s) to set. Can be a single

synapseclient/models/project_setting.py

@@ -37,11 +37,41 @@ class ProjectSetting(ProjectSettingSynchronousProtocol):
             is supported. Default: ``"upload"``.
         locations: The list of storage location IDs for upload. The first ID is the
             default upload destination. A project may have at most 10 storage locations.
+            To obtain a storage location ID, create a
+            [StorageLocation][synapseclient.models.StorageLocation] and use its
+            `storage_location_id`. See
+            [StorageLocationType][synapseclient.models.StorageLocationType] for the
+            available storage backend types.
         concrete_type: (Read Only) The concrete type returned by the Synapse REST API.
         etag: (Read Only) Synapse employs an Optimistic Concurrency Control (OCC)
             scheme. The etag changes every time the setting is updated; it must be
             included on updates.
 
+    Example: Creating a project setting from a new storage location:
+        Create a StorageLocation first, then use its ID when creating the
+        project setting:
+
+            from synapseclient.models import (
+                ProjectSetting,
+                StorageLocation,
+                StorageLocationType,
+            )
+
+            import synapseclient
+            synapseclient.login()
+
+            storage = StorageLocation(
+                storage_type=StorageLocationType.EXTERNAL_S3,
+                bucket="my-bucket",
+                base_key="my/prefix",
+            ).store()
+
+            setting = ProjectSetting(
+                project_id="syn123",
+                locations=[storage.storage_location_id],
+            ).store()
+            print(f"Created setting ID: {setting.id}")
+
     Example: Creating a project setting:
 
             from synapseclient.models import ProjectSetting
@@ -95,7 +125,11 @@ class ProjectSetting(ProjectSettingSynchronousProtocol):
 
     locations: List[int] = field(default_factory=list)
     """The list of storage location IDs for upload. The first ID is the default upload
-    destination. A project may have at most 10 storage locations."""
+    destination. A project may have at most 10 storage locations. To obtain a storage
+    location ID, create a [StorageLocation][synapseclient.models.StorageLocation] and
+    use its `storage_location_id`. See
+    [StorageLocationType][synapseclient.models.StorageLocationType] for the available
+    storage backend types."""
 
     concrete_type: Optional[str] = field(default=None, compare=False)
     """(Read Only) The concrete type returned by the Synapse REST API."""