convert comments above functions to python docstrings

This is how to write per-function comments.
https://www.python.org/dev/peps/pep-0257/

fdroidserver/common.py

@@ -358,9 +358,11 @@ def get_local_metadata_files():
     return glob.glob('.fdroid.[a-jl-z]*[a-rt-z]')
 
 
-# Given the arguments in the form of multiple appid:[vc] strings, this returns
-# a dictionary with the set of vercodes specified for each package.
 def read_pkg_args(args, allow_vercodes=False):
+    """
+    Given the arguments in the form of multiple appid:[vc] strings, this returns
+    a dictionary with the set of vercodes specified for each package.
+    """
 
     vercodes = {}
     if not args:
@@ -380,9 +382,11 @@ def read_pkg_args(args, allow_vercodes=False):
     return vercodes
 
 
-# On top of what read_pkg_args does, this returns the whole app metadata, but
-# limiting the builds list to the builds matching the vercodes specified.
 def read_app_args(args, allapps, allow_vercodes=False):
+    """
+    On top of what read_pkg_args does, this returns the whole app metadata, but
+    limiting the builds list to the builds matching the vercodes specified.
+    """
 
     vercodes = read_pkg_args(args, allow_vercodes)
 
@@ -979,8 +983,8 @@ def retrieve_string_singleline(app_dir, string, xmlfiles=None):
     return retrieve_string(app_dir, string, xmlfiles).replace('\n', ' ').strip()
 
 
-# Return list of existing files that will be used to find the highest vercode
 def manifest_paths(app_dir, flavours):
+    '''Return list of existing files that will be used to find the highest vercode'''
 
     possible_manifests = \
         [os.path.join(app_dir, 'AndroidManifest.xml'),
@@ -997,8 +1001,8 @@ def manifest_paths(app_dir, flavours):
     return [path for path in possible_manifests if os.path.isfile(path)]
 
 
-# Retrieve the package name. Returns the name, or None if not found.
 def fetch_real_name(app_dir, flavours):
+    '''Retrieve the package name. Returns the name, or None if not found.'''
     for path in manifest_paths(app_dir, flavours):
         if not has_extension(path, 'xml') or not os.path.isfile(path):
             continue
@@ -1070,10 +1074,12 @@ def app_matches_packagename(app, package):
     return appid == package
 
 
-# Extract some information from the AndroidManifest.xml at the given path.
-# Returns (version, vercode, package), any or all of which might be None.
-# All values returned are strings.
 def parse_androidmanifests(paths, app):
+    """
+    Extract some information from the AndroidManifest.xml at the given path.
+    Returns (version, vercode, package), any or all of which might be None.
+    All values returned are strings.
+    """
 
     ignoreversions = app.UpdateCheckIgnore
     ignoresearch = re.compile(ignoreversions).search if ignoreversions else None

fdroidserver/metadata.py

@@ -152,24 +152,30 @@ class App():
         self.lastupdated = None
         self._modified = set()
 
-    # Translates human-readable field names to attribute names, e.g.
-    # 'Auto Name' to 'AutoName'
     @classmethod
     def field_to_attr(cls, f):
+        """
+        Translates human-readable field names to attribute names, e.g.
+        'Auto Name' to 'AutoName'
+        """
         return f.replace(' ', '')
 
-    # Translates attribute names to human-readable field names, e.g.
-    # 'AutoName' to 'Auto Name'
     @classmethod
     def attr_to_field(cls, k):
+        """
+        Translates attribute names to human-readable field names, e.g.
+        'AutoName' to 'Auto Name'
+        """
         if k in app_fields:
             return k
         f = re.sub(r'([a-z])([A-Z])', r'\1 \2', k)
         return f
 
-    # Constructs an old-fashioned dict with the human-readable field
-    # names. Should only be used for tests.
     def field_dict(self):
+        """
+        Constructs an old-fashioned dict with the human-readable field
+        names. Should only be used for tests.
+        """
         d = {}
         for k, v in self.__dict__.items():
             if k == 'builds':
@@ -182,23 +188,23 @@ class App():
                 d[f] = v
         return d
 
-    # Gets the value associated to a field name, e.g. 'Auto Name'
     def get_field(self, f):
+        """Gets the value associated to a field name, e.g. 'Auto Name'"""
         if f not in app_fields:
             warn_or_exception('Unrecognised app field: ' + f)
         k = App.field_to_attr(f)
         return getattr(self, k)
 
-    # Sets the value associated to a field name, e.g. 'Auto Name'
     def set_field(self, f, v):
+        """Sets the value associated to a field name, e.g. 'Auto Name'"""
         if f not in app_fields:
             warn_or_exception('Unrecognised app field: ' + f)
         k = App.field_to_attr(f)
         self.__dict__[k] = v
         self._modified.add(k)
 
-    # Appends to the value associated to a field name, e.g. 'Auto Name'
     def append_field(self, f, v):
+        """Appends to the value associated to a field name, e.g. 'Auto Name'"""
         if f not in app_fields:
             warn_or_exception('Unrecognised app field: ' + f)
         k = App.field_to_attr(f)
@@ -207,8 +213,8 @@ class App():
         else:
             self.__dict__[k].append(v)
 
-    # Like dict.update(), but using human-readable field names
     def update_fields(self, d):
+        '''Like dict.update(), but using human-readable field names'''
         for f, v in d.items():
             if f == 'builds':
                 for b in v:
@@ -772,9 +778,11 @@ def read_srclibs():
         srclibs[srclibname] = parse_srclib(metadatapath)
 
 
-# Read all metadata. Returns a list of 'app' objects (which are dictionaries as
-# returned by the parse_txt_metadata function.
 def read_metadata(xref=True):
+    """
+    Read all metadata. Returns a list of 'app' objects (which are dictionaries as
+    returned by the parse_txt_metadata function.
+    """
 
     # Always read the srclibs before the apps, since they can use a srlib as
     # their source repository.