Biopython: D103 Missing docstring in public function

[peterjc]

We currently enforce various code style issues using flake8, configured via Bio/.flake8 etc and run automatically on TravisCI via tox. More details here including how to install flake8 and the relevant plugins:

https://github.com/biopython/biopython/blob/master/CONTRIBUTING.rst

One of the important docstring checks we currently do not enforce is missing docstrings in public functions.

This issue to to add the remaining missing function docstrings, and then turn on the D103 checks by removing them from the ignore list here:

https://github.com/biopython/biopython/blob/master/Bio/.flake8

Currently there are just 24 of these remaining following work on issue #1203 etc:

$ flake8 Bio BioSQL --isolated --select D103 | sort
Bio/Crystal/__init__.py:24:1: D103 Missing docstring in public function
Bio/Crystal/__init__.py:31:1: D103 Missing docstring in public function
Bio/Entrez/Parser.py:305:1: D103 Missing docstring in public function
Bio/FSSP/__init__.py:232:1: D103 Missing docstring in public function
Bio/Geo/Record.py:87:1: D103 Missing docstring in public function
Bio/Geo/__init__.py:27:1: D103 Missing docstring in public function
Bio/KEGG/Map/__init__.py:22:1: D103 Missing docstring in public function
Bio/PopGen/GenePop/LargeFileParser.py:20:1: D103 Missing docstring in public function
Bio/PopGen/GenePop/__init__.py:25:1: D103 Missing docstring in public function
Bio/SeqIO/NibIO.py:63:1: D103 Missing docstring in public function
Bio/SeqIO/TabIO.py:112:1: D103 Missing docstring in public function
Bio/SubsMat/FreqTable.py:82:1: D103 Missing docstring in public function
Bio/SubsMat/FreqTable.py:91:1: D103 Missing docstring in public function
Bio/SwissProt/KeyWList.py:55:1: D103 Missing docstring in public function
Bio/SwissProt/__init__.py:134:1: D103 Missing docstring in public function
Bio/SwissProt/__init__.py:142:1: D103 Missing docstring in public function
Bio/UniGene/__init__.py:253:1: D103 Missing docstring in public function
Bio/UniGene/__init__.py:261:1: D103 Missing docstring in public function
Bio/Wise/__init__.py:136:1: D103 Missing docstring in public function
Bio/Wise/dnal.py:118:1: D103 Missing docstring in public function
Bio/Wise/dnal.py:131:1: D103 Missing docstring in public function
Bio/Wise/psw.py:131:1: D103 Missing docstring in public function
Bio/Wise/psw.py:148:1: D103 Missing docstring in public function
Bio/codonalign/codonalphabet.py:35:1: D103 Missing docstring in public function

This is fairly simple to fix, so I've tagged is as a "good first issue" and would particularly like to encourage new contributors to try working on this (although code authors are of course also welcome to fix their own omissions).

If you want to volunteer and work on a section, please comment here first to avoid duplication of effort. e.g. "I'll work on Bio/Wise/"

If you want to work on this as #1961 together, that's fine too.

[tmnnt]

Hey
I would like to work on this

[MarkusPiotrowski]

@tmnnt Please select a module on which you would like to work on and tell us.

If you are not experienced with doscstrings, I would suggest to read PEP 257 beforehand: https://www.python.org/dev/peps/pep-0257/

To write a meaninful docstring, you should try to understand what the function is really doing.

[svalqui]

Updated list:

$ flake8 Bio BioSQL --isolated --select D103 | sort
Bio/codonalign/codonalphabet.py:35:1: D103 Missing docstring in public function
Bio/Geo/__init__.py:27:1: D103 Missing docstring in public function
Bio/Geo/Record.py:87:1: D103 Missing docstring in public function
Bio/SeqIO/NibIO.py:63:1: D103 Missing docstring in public function
Bio/SeqIO/TabIO.py:112:1: D103 Missing docstring in public function
Bio/SwissProt/__init__.py:134:1: D103 Missing docstring in public function
Bio/SwissProt/__init__.py:142:1: D103 Missing docstring in public function
Bio/SwissProt/KeyWList.py:55:1: D103 Missing docstring in public function
Bio/UniGene/__init__.py:253:1: D103 Missing docstring in public function
Bio/UniGene/__init__.py:261:1: D103 Missing docstring in public function

[svalqui]

I'll work on Bio.UniGene.

[peterjc]

@svalqui assuming we get a lightning talk slot at BOSC 2019 for the Biopython Project Update this summer, you definitely deserve your name on the slide talking about filling in the missing API documentation 🥇

[MarkusPiotrowski]

I'm working at the last missing D103 issues.

[svalqui]

@peterjc that's great, thank you. I think think this issue will be closing soon.

[peterjc]

Indeed 👍