Fix up comments

synapse/rest/media/v1/_base.py

@@ -136,8 +136,8 @@ def respond_with_responder(request, responder, media_type, file_size, upload_nam
         request (twisted.web.http.Request)
         responder (Responder|None)
         media_type (str): The media/content type.
-        file_size (int): Size in bytes of the media. If not known it should be None
-        upload_name (str): The name of the requested file, if any.
+        file_size (int|None): Size in bytes of the media. If not known it should be None
+        upload_name (str|None): The name of the requested file, if any.
     """
     if not responder:
         respond_404(request)

synapse/rest/media/v1/media_repository.py

@@ -161,11 +161,12 @@ class MediaRepository(object):
 
         Args:
             request(twisted.web.http.Request)
-            media_id (str)
+            media_id (str): The media ID of the content. (This is the same as
+                the file_id for local content.)
             name (str|None): Optional name that, if specified, will be used as
                 the filename in the Content-Disposition header of the response.
 
-        Retruns:
+        Returns:
             Deferred: Resolves once a response has successfully been written
                 to request
         """
@@ -196,11 +197,12 @@ class MediaRepository(object):
         Args:
             request(twisted.web.http.Request)
             server_name (str): Remote server_name where the media originated.
-            media_id (str)
+            media_id (str): The media ID of the content (as defined by the
+                remote server).
             name (str|None): Optional name that, if specified, will be used as
                 the filename in the Content-Disposition header of the response.
 
-        Retruns:
+        Returns:
             Deferred: Resolves once a response has successfully been written
                 to request
         """
@@ -230,6 +232,11 @@ class MediaRepository(object):
         """Looks for media in local cache, if not there then attempt to
         download from remote server.
 
+        Args:
+            server_name (str): Remote server_name where the media originated.
+            media_id (str): The media ID of the content (as defined by the
+                remote server).
+
         Returns:
             Deferred[(Responder, media_info)]
         """
@@ -272,7 +279,9 @@ class MediaRepository(object):
 
         Args:
             server_name (str): Originating server
-            media_id (str)
+            media_id (str): The media ID of the content (as defined by the
+                remote server). This is different than the file_id, which is
+                locally generated.
             file_id (str): Local file ID
 
         Returns: