Regarding the TODO: "Figure out a style for Sphinx-type
documentation", here are my thoughts:
- As a general rule, I guess a comment block should always be
associated with the next language element.
- The script itslef should start with a block describing the
overall purpose of the script and perhaps potential
caveats/things to keep in mind etc.
- Each indidivual doc section should start with a single short
sentence summarizing the documented element, followed by further
text going into more detail.
- Generally, all doc text is formatted in reST. However, one
thing I always hate when writing documentation strings is adding
all kinds of markers for things like parameters, return values,
etc. (e.g., "@param", or ":param:"). What I've played with for
HILTI is reducing this stuff to a minimum and extracting it from
the structure of the text. Example:
# Function for checking That.