Ticket #8958 (new enhancement)
Extend/clarify/normalize the conventions for Python/Cython docstrings
|Reported by:||leif||Owned by:||mvngu|
|Component:||documentation||Keywords:||docstring, documentation string, convention, style|
The section of the Developer's Guide on conventions for (Python/Cython?) docstrings within Sage http://www.sagemath.org/doc/developer/conventions.html#documentation-strings currently lacks some issues; also IMHO the usage of inline literals for Python names/types etc., default-role interpreted text (i.e. [LaTeX] math mode) and the syntax/style of e.g. parameter and return type descriptions should be normalized (further).
- A description of the :class:, :meth:, :func: etc. roles is completely missing.
- We currently have at least both
- ``param`` -- (type, default val) other description...
- ``param`` (type, default val) -- other description...,
where the latter (without the default) is used by Sphinx.
- True and False etc. are usually written/typeset as literals (``True``), while other Python names and types (e.g. int) are not. (Perhaps a bad example, since one could even use :class:`int`.)
- True function/return type descriptions use both indicative and imperative mood, sometimes even within the same module/file. (Same for procedures, i.e. "functions" doing something but not returning anything.)
- Some people use math mode also for isolated numbers (`1`) and/or numbers within words (e.g. `2`-descent instead of 2-descent), but not necessarily consistently. The HTML output of that looks very ugly, as does e.g. that of `L`-functions. (There are at least four variants of how simple constraints or case distinctions like "n < 42" are written, namely without mark-up, entirely literal, partially or completely typeset in math mode, and as mixtures of plain, literal/verbatim and math mode; "... less than 42" of course is another option.)
- IMHO the type descriptions should be specific if a function actually expects (or returns) some particular type. (Once we switch to Python 3, we can use type annotations, too... ;-) )
- What about documenting potentially raised exceptions?
- Some frequently used names etc. (even e.g. int) could be defined as (global) macros (e.g. |int|) to achieve consistent look (this also applies to reST documentation within Sage in general).
(The above list is most probably not exhaustive, nor does it express any importance/priority; additions welcome.)
Besides extending the documentation, we should perhaps discuss some issues and/or hold votes for the preferred/recommended style on sage-devel. :)