Improve getAffiliation docstring to follow numpy/scipy documentation #98
Conversation
odm2api/ODM2/services/readService.py
Outdated
| * Pass a First Name - returns a single Affiliation object | ||
| * Pass a Last Name - returns a single Affiliation object | ||
| * Pass an OrganizationCode - returns a Affiliation object | ||
| Retrieve a list of ODM2 Affiliation objects. |
There was a problem hiding this comment.
Based on the behavior described in the old docstring, I'd change this to: "Retrieve an Affiliation object or a list of such objects." But please confirm whether a request that returns one object, returns a list with one element or the object proper. Adjust the above string as appropriate.
There was a problem hiding this comment.
The previous docstring seems to be incorrect, the function always returns a list...
There was a problem hiding this comment.
Ok. Glad you checked it!
I would just remove "ODM2" from the string. It's obvious that odm2api query methods all return ODM2 objects!
odm2api/ODM2/services/readService.py
Outdated
| Person Last Name | ||
| orgcode: str, default None | ||
| Organization Code | ||
|
|
There was a problem hiding this comment.
Looks like if you call the function with no arguments (or None for all / any of them), a list of ALL affiliations will be returned. Tweak the docstring to include that information.
There was a problem hiding this comment.
Should I say:
Retrieve a list of ODM2 Affiliation objects.
Note: If no arguments are passed to the function,
ALL ODM2 Affiliation objects within the database will be queried.
There was a problem hiding this comment.
Retrieve a list of Affiliation objects.
If no arguments are passed to the function, or their values are None,
all Affiliation objects in the database will be returned.
odm2api/ODM2/services/readService.py
Outdated
| * Pass an OrganizationCode - returns a Affiliation object | ||
| Retrieve a list of ODM2 Affiliation objects. | ||
|
|
||
| Parameters |
There was a problem hiding this comment.
We may need the numpydoc extension for this. I don't have a strong preference but lately I've stop using numpy-style and adopted the simpler http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html
There was a problem hiding this comment.
I don't know much about the two styles, so I'll go with whatever @ocefpaf recommends! Can you tell us why you've made the change (pros and cons), offline? Say, on the email thread we started yesterday about documentation?
odm2api/ODM2/services/readService.py
Outdated
| >>> read.getAffiliations(personfirst='Anthony', | ||
| ... personlast='Aufdenkampe') | ||
| >>> read.getAffiliations(orgcode='LimnoTech') | ||
|
|
There was a problem hiding this comment.
Change the examples so they don't refer to Anthony's actual identity (first & last name and actual organization)! Use made up names and organization code, eg: John Smith, orgcode='Acme'
| all Affiliation objects in the database will be returned. | ||
|
|
||
| Args: | ||
| ids (:obj:`list`, optional): List of AffiliationIDs. Defaults to None. |
|
I'm merging ... |
Overview
This PR improves the docstring for
getAffiliationsto follow the numpy/scipy documentation standard. If you have suggestions of better wordings, please let me know. This relates to #97.