[python] Dokumentace, komentáře

[Bystroushaak]

Co se dokumentačních komentářů týče, tak je tady PEP 257
(http://legacy.python.org/dev/peps/pep-0257/), který z mé zkušenosti
funguje dobře pro malé projekty, dokud z toho nepotřebuješ nějak
generovat různé (online) nápovědy.

V minulosti jsem používal Epydoc (http://epydoc.sourceforge.net/), který
nebyl úplně špatný, ale přeci jen ten zápis se (ve zdrojáku) nečte úplně
pohodlně.

V práci teď používám Sphinx s modulem Napoleon
(http://sphinxcontrib-napoleon.readthedocs.org), což je styl
dokumentačních komentářů původě vymyšlený googlem.

Místo abys psal ve sphinxu cosi jako;

---
:param path: The path of the file to wrap
:type path: str
:param field_storage: The :class:`FileStorage` instance to wrap
:type field_storage: FileStorage
:param temporary: Whether or not to delete the file when the File
   instance is destructed
:type temporary: bool
:returns: A buffered writable file descriptor
:rtype: BufferedFileStorage
---

Tak píšeš poměrně čitelným stylem:

---
Args:
    path (str): The path of the file to wrap
    field_storage (FileStorage): The :class:`FileStorage` instance to wrap
    temporary (bool): Whether or not to delete the file when the File
       instance is destructed

Returns:
    BufferedFileStorage: A buffered writable file descriptor
---

Vygenerovaná dokumentace je pak klasický Sphinx (veškerá python core
dokumentace je ve Sphinxu, takže předpokládám že všichni znají).