Improve docstrings

ckanext/attribution/commands/migration/api_search.py

@@ -50,7 +50,7 @@ def _search_api(self, contrib, lookup, api_name, result_format):
         :param lookup: dict of query params (plus display_name) to send to api.search
         :param api_name: name of the API (see self.api)
         :param result_format: display format of each result, e.g. "{name} ({location})"
-        :return: None if not found, dict for matching result if found/selected
+        :returns: None if not found, dict for matching result if found/selected
         """
         check_installed(cli_installed)
 

ckanext/attribution/commands/migration/combiner.py

@@ -35,7 +35,7 @@ def separate(self, group):
 
         :param group: a list of ParsedSegment instances that are probably the same
             contributor
-        :return: a list of lists of ParsedSegments
+        :returns: a list of lists of ParsedSegments
         """
         all_names = sorted(
             list(set([str(x.name) for x in group])), key=lambda x: -len(x)
@@ -96,7 +96,7 @@ def combine_person_names(self, names):
         """
         Uses a list of HumanNames to determine the longest possible name for a person.
 
-        :return: a dict of family_name, given_names (includes middle names), and key
+        :returns: a dict of family_name, given_names (includes middle names), and key
             (i.e. a sort/display name)
         """
         check_installed(cli_installed)
@@ -168,7 +168,7 @@ def run(self):
         Run the combiner over the whole parser list, including separating groups,
         combining names, searching APIs, and updating the affiliations dict.
 
-        :return: a list of contributors
+        :returns: a list of contributors
         """
         combined = []
 

ckanext/attribution/commands/migration/common.py

@@ -14,7 +14,7 @@ def multi_choice(question, options, default=0):
     """
     Provide the user with a list of options.
 
-    :return: index of the chosen option
+    :returns: index of the chosen option
     """
     click.echo(question)
     for i, o in enumerate(options):

ckanext/attribution/commands/migration/parser.py

@@ -54,7 +54,7 @@ def run(self, txt, pkg_id, contrib_type):
         :param txt: the chunk of text to process
         :param pkg_id: associated package
         :param contrib_type: author, contributor, or affiliation
-        :return: list of ParsedSegment instances extracted from the text
+        :returns: list of ParsedSegment instances extracted from the text
         """
         if not self.validate(txt):
             return
@@ -107,7 +107,7 @@ def validate(self, txt):
         """
         Check the text can/should actually be parsed.
 
-        :return: True/False
+        :returns: True/False
         """
         if txt is None:
             return False
@@ -129,8 +129,8 @@ def split(self, txt):
         Uses multiple sub-methods to attempt to split the text into individual
         contributors.
 
-        :param txt:
-        :return:
+        :param txt: a string containing multiple contributor names
+        :returns: a list of names
         """
         lines = [ln.strip() for ln in txt.split('\n')]
         segments = [
@@ -224,7 +224,7 @@ def extract_affiliations(self, txt):
         """
         Uses regexes to find probable affiliations in parentheses.
 
-        :return: contributor name, list of affiliations
+        :returns: contributor name, list of affiliations
         """
         has_affiliation = rgx.has_affiliation.match(txt)
         no_affiliation = rgx.no_affiliation.match(txt)

ckanext/attribution/lib/helpers.py

@@ -16,7 +16,7 @@ def can_edit():
     """
     Check editing permissions for updating agent directly.
 
-    :return:
+    :returns: True if user can edit agents, False if not
     """
     try:
         permitted = toolkit.check_access('agent_update', {}, {})
@@ -34,8 +34,8 @@ def get_contributions(pkg_id):
     Template access for the
     :func:`~ckanext.attribution.model.crud.PackageQuery.get_contributions` query method.
 
-    :param pkg_id:
-    :return:
+    :param pkg_id: the ID of the package
+    :returns: list of activities associated with the package
     """
     return PackageQuery.get_contributions(pkg_id)
 

ckanext/attribution/logic/actions/meta/help.py

@@ -131,7 +131,7 @@
 
 :param lists: names of the lists to be returned
 :type lists: list, optional
-:return: dict of all requested lists (or all lists if unspecified)
+:returns: dict of all requested lists (or all lists if unspecified)
 :rtype: dict
 """
 
@@ -169,7 +169,7 @@
 :type external_id: str
 :param external_id_scheme: external scheme, e.g. orcid
 :type external_id_scheme: str
-:return:
+:returns: dict containing the ID if valid and any errors
 """
 
 # SHOW =============================================================================================
@@ -281,8 +281,8 @@
 :type start_date: datetime.date, optional
 :param end_date: when the affiliation ended (e.g. when a researcher left an institution)
 :type end_date: datetime.date, optional
-:param context:
-:param data_dict:
+:param context: request context
+:param data_dict: request data
 :returns: The updated agent affiliation record.
 :rtype: dict
 """
@@ -307,8 +307,8 @@
 :type user_id: str, optional
 :param name: name of an organisation [org only]
 :type name: str, optional
-:param context:
-:param data_dict:
+:param context: request context
+:param data_dict: request data
 :returns: The updated agent record.
 :rtype: dict
 """
@@ -339,8 +339,8 @@
 :type level: str, optional
 :param time: time activity took place
 :type time: datetime.datetime, optional
-:param context:
-:param data_dict:
+:param context: request context
+:param data_dict: request data
 :returns: New contribution activity record.
 :rtype: dict
 """

ckanext/attribution/model/agent.py

@@ -55,9 +55,9 @@ def display_name(self):
     @property
     def standardised_name(self):
         """
-        Family name first for persons.
+        Name in a standardised format.
 
-        :return:
+        :returns: full name (family name first) for person names, just name for other
         """
         if self.agent_type == 'person':
             return ', '.join([self.family_name, self.given_names])

ckanext/attribution/model/crud/_base.py

@@ -92,7 +92,7 @@ def exists(cls, item_id):
         Check if a record with the given ID exists.
 
         :param item_id: the ID of the potential record
-        :return: bool
+        :returns: bool
         """
         return Session.query(cls.m).get(item_id) is not None
 

ckanext/attribution/routes/user.py

@@ -18,7 +18,7 @@ def datasets(username):
     Render a list of datasets that this user has contributed to.
 
     :param username: The username
-    :return: str
+    :returns: str
     """
     try:
         toolkit.check_access('user_show', {}, {'id': username})