Explicit parameter list in function documentation

Documentation
15

A more typical example, picked somewhat arbitrarily from the docs I had open, is, say, the logging.Formatter class constructor, which has a medium number of parameters (5). At present, the parameters are buried in the prose, and one isn’t even mentioned there at all; users have to read through Changed in version 3.8 annotation at the end to even find it. Furthermore, it contains a lot of duplicate information split between the section introduction and class object itself.

Revised to use standard Sphinxdoc fields (since several other callables in the document use it, its built into regular Sphinx, is designed and intended for this purpose, and allows easily enhancing/changing the layout, styling, index etc. in one place without touching the content), I find it much more suited to its intended purpose—a quickly-accessed, succinct, complete and unambiguous reference to the constructor, communicating the same information (and more) in a much more useful way: [1]

image
image1890×716 112 KB

The logging module docs also a great example of the present lack of even basic consistency in how parameters are presented:

They’re a mix of constructors, functions and methods, adjacent in the same document, each having between a half dozen and a dozen parameters, with no clear motivation for the potporri other than whatever the individual contributor happened to use at the time. Documenting and implementing a consistent, tailored structure for this information makes it much easier for readers to quickly recognize and reference without the cognitive burden of processing three different representations, and avoids doc contributors having to manually guess at how they should ideally represent it.

  1. The current styling isn’t ideal; its a little dense and could use a little more whitespace, but that’s easy to tweak in the stylesheet/theme—see, for example, how Lutra currently looks for another constructor in this module ↩︎

8 Likes