Address feedback, make docstrings less imperative

WordPress · May 6, 2024 · b93d52b · b93d52b
1 parent c57fda4
commit b93d52b
Show file tree

Hide file tree

Showing 5 changed files with 32 additions and 41 deletions.
diff --git a/api/api/migrations/0060_fill_out_help_text.py b/api/api/migrations/0060_fill_out_help_text.py
@@ -28,7 +28,7 @@ class Migration(migrations.Migration):
         migrations.AlterField(
             model_name='audio',
             name='removed_from_source',
-            field=models.BooleanField(default=False, help_text='Whether or not the media has been removed from the upstream source.'),
+            field=models.BooleanField(default=False, help_text='Whether the media has been removed from the upstream source.'),
         ),
         migrations.AlterField(
             model_name='audio',
@@ -58,7 +58,7 @@ class Migration(migrations.Migration):
         migrations.AlterField(
             model_name='image',
             name='removed_from_source',
-            field=models.BooleanField(default=False, help_text='Whether or not the media has been removed from the upstream source.'),
+            field=models.BooleanField(default=False, help_text='Whether the media has been removed from the upstream source.'),
         ),
         migrations.AlterField(
             model_name='image',

diff --git a/api/api/models/audio.py b/api/api/models/audio.py
@@ -141,7 +141,7 @@ class AudioAddOn(OpenLedgerModel):
 
 class Audio(AudioFileMixin, AbstractMedia):
     """
-    Represents one audio media instance.
+    One audio media instance.
 
     Inherited fields
     ================
@@ -254,7 +254,7 @@ class Meta(AbstractMedia.Meta):
 
 class DeletedAudio(AbstractDeletedMedia):
     """
-    Represents audio tracks deleted from the upstream source.
+    Audio tracks deleted from the upstream source.
 
     Do not create instances of this model manually. Create an ``AudioReport`` instance
     instead.
@@ -280,7 +280,7 @@ class Meta:
 
 class SensitiveAudio(AbstractSensitiveMedia):
     """
-    Represents audio tracks with verified sensitivity reports.
+    Audio tracks with verified sensitivity reports.
 
     Do not create instances of this model manually. Create an ``AudioReport`` instance
     instead.
@@ -307,7 +307,7 @@ class Meta:
 
 class AudioReport(AbstractMediaReport):
     """
-    Represents user-submitted reports of audio tracks.
+    User-submitted reports of audio tracks.
 
     ``AudioDecision`` is populated only if moderators have made a decision
     for this report.
@@ -337,7 +337,7 @@ class Meta:
 
 
 class AudioDecision(AbstractMediaDecision):
-    """Represents moderation decisions taken for audio tracks."""
+    """Moderation decisions taken for audio tracks."""
 
     media_class = Audio
 
@@ -349,7 +349,7 @@ class AudioDecision(AbstractMediaDecision):
 
 
 class AudioList(AbstractMediaList):
-    """Represents a list of audio files. Currently unused."""
+    """A list of audio files. Currently unused."""
 
     audios = models.ManyToManyField(
         Audio,

diff --git a/api/api/models/image.py b/api/api/models/image.py
@@ -43,7 +43,7 @@ class Meta:
 
 class Image(ImageFileMixin, AbstractMedia):
     """
-    Represents one image media instance.
+    One image media instance.
 
     Inherited fields
     ================
@@ -60,7 +60,7 @@ def sensitive(self) -> bool:
 
 class DeletedImage(AbstractDeletedMedia):
     """
-    Represents images deleted from the upstream source.
+    Images deleted from the upstream source.
 
     Do not create instances of this model manually. Create an ``ImageReport`` instance
     instead.
@@ -83,7 +83,7 @@ class DeletedImage(AbstractDeletedMedia):
 
 class SensitiveImage(AbstractSensitiveMedia):
     """
-    Represents images with verified sensitivity reports.
+    Images with verified sensitivity reports.
 
     Do not create instances of this model manually. Create an ``ImageReport`` instance
     instead.
@@ -139,7 +139,7 @@ class Meta:
 
 
 class ImageDecision(AbstractMediaDecision):
-    """Represents moderation decisions taken for images."""
+    """Moderation decisions taken for images."""
 
     media_class = Image
 
@@ -151,7 +151,7 @@ class ImageDecision(AbstractMediaDecision):
 
 
 class ImageList(AbstractMediaList):
-    """Represents a list of images. Currently unused."""
+    """A list of images. Currently unused."""
 
     images = models.ManyToManyField(
         Image,

diff --git a/api/api/models/media.py b/api/api/models/media.py
@@ -1,6 +1,6 @@
 import logging
 import mimetypes
-from textwrap import dedent as d
+from textwrap import dedent
 
 from django.conf import settings
 from django.core.exceptions import ValidationError
@@ -87,8 +87,7 @@ class AbstractMedia(
     tags = models.JSONField(
         blank=True,
         null=True,
-        help_text=d(
-            """
+        help_text=dedent("""
         JSON array of objects containing tags for the media. Each tag object
         is expected to have:
 
@@ -98,8 +97,7 @@ class AbstractMedia(
         for that label expressed as a value between 0 and 1.
 
         Note that only `name` and `accuracy` are presently surfaced in API results.
-        """
-        ),
+        """),
     )
 
     category = models.CharField(
@@ -113,14 +111,12 @@ class AbstractMedia(
     meta_data = models.JSONField(
         blank=True,
         null=True,
-        help_text=d(
-            """
+        help_text=dedent("""
         JSON object containing extra data about the media item. No fields are expected,
         but if the `license_url` field is available, it will be used for determining
         the license URL for the media item. The `description` field, if available, is
         also indexed into Elasticsearch and as a search field on queries.
-        """
-        ),
+        """),
     )
 
     @property

diff --git a/documentation/meta/media_properties/api.md b/documentation/meta/media_properties/api.md
@@ -86,10 +86,10 @@ Each object is expected to contain:
 
 #### `audio_report`
 
-**Model docstring:** Represents audio tracks that have been reported by users.
+**Model docstring:** User-submitted reports of audio tracks.
 
-This contains an `AudioDecision` as well, if moderators have made a decision for
-this report.
+`AudioDecision` is populated only if moderators have made a decision for this
+report.
 
 (Audio-audio_set_foreign_identifier-notes)=
 
@@ -107,7 +107,7 @@ this report.
 
 #### `audiodecision`
 
-**Model docstring:** Represents moderation decisions taken for audio tracks.
+**Model docstring:** Moderation decisions taken for audio tracks.
 
 (Audio-audioset-notes)=
 
@@ -152,8 +152,7 @@ The FileMixin inherited by this model refers not to audio but album art.
 
 #### `deleted_audio`
 
-**Model docstring:** Represents audio tracks that have been deleted from the
-source.
+**Model docstring:** Audio tracks deleted from the upstream source.
 
 Do not create instances of this model manually. Create an `AudioReport` instance
 instead.
@@ -230,7 +229,7 @@ explicitly.
 
 #### `lists`
 
-**Model docstring:** Represents a list of audio files. Currently unused.
+**Model docstring:** A list of audio files. Currently unused.
 
 (Audio-meta_data-notes)=
 
@@ -251,8 +250,7 @@ available, is also indexed into Elasticsearch and as a search field on queries.
 
 #### `removed_from_source`
 
-**Help text:** Whether or not the media has been removed from the upstream
-source.
+**Help text:** Whether the media has been removed from the upstream source.
 
 (Audio-sample_rate-notes)=
 
@@ -264,8 +262,7 @@ source.
 
 #### `sensitive_audio`
 
-**Model docstring:** Represents audio tracks that have been flagged and verified
-as 'mature'.
+**Model docstring:** Audio tracks with verified sensitivity reports.
 
 Do not create instances of this model manually. Create an `AudioReport` instance
 instead.
@@ -389,7 +386,7 @@ Note that only `name` and `accuracy` are presently surfaced in API results.
 
 #### `deleted_image`
 
-**Model docstring:** Represents images that have been deleted from the source.
+**Model docstring:** Images deleted from the upstream source.
 
 Do not create instances of this model manually. Create an `ImageReport` instance
 instead.
@@ -441,7 +438,7 @@ explicitly.
 
 #### `image_report`
 
-**Model docstring:** Represents images that have been reported by users.
+**Model docstring:** User-submitted report of an image.
 
 This contains an `ImageDecision` as well, if moderators have made a decision for
 this report.
@@ -450,7 +447,7 @@ this report.
 
 #### `imagedecision`
 
-**Model docstring:** Represents moderation decisions taken for images.
+**Model docstring:** Moderation decisions taken for images.
 
 (Image-last_synced_with_source-notes)=
 
@@ -474,7 +471,7 @@ this report.
 
 #### `lists`
 
-**Model docstring:** Represents a list of images. Currently unused.
+**Model docstring:** A list of images. Currently unused.
 
 (Image-meta_data-notes)=
 
@@ -495,15 +492,13 @@ available, is also indexed into Elasticsearch and as a search field on queries.
 
 #### `removed_from_source`
 
-**Help text:** Whether or not the media has been removed from the upstream
-source.
+**Help text:** Whether the media has been removed from the upstream source.
 
 (Image-sensitive_image-notes)=
 
 #### `sensitive_image`
 
-**Model docstring:** Represents images that have been flagged and verified as
-'mature'.
+**Model docstring:** Images with verified sensitivity reports.
 
 Do not create instances of this model manually. Create an `ImageReport` instance
 instead.