@astropy/astropy-core-maintainers - quite a while ago (#4821), @astrofrog suggested that it might be good to have implementation notes in some standard place, i.e., notes about the design of a given module. At the time, he considered a separate file, but it was felt that really this should be part of the documentation.

I am reopening this discussion because of #8902, in which @taldcroft adds an _implementation_note docstring to table.py, which has some very useful "developer-beware" notes. I think it would be good to have a standard way to do this, and in particular to ensure such notes become part of the documentation.

My own suggestion is a very simple one: let's use the module docstring for implementation notes. Currently, these are essentially unused (see below for examples from time/core.py and units/quantity.py). Obviously, they will be typeset as part of the API by sphinx, which I think is file.

If we go this route, we could do worse than just start by following the numpydoc guide, which suggests the following sections:

1. summary
2. extended summary
3. routine listings
4. see also
5. notes
6. references
7. examples

Examples

# time/core.py
"""
The astropy.time package provides functionality for manipulating times and
dates. Specific emphasis is placed on supporting time scales (e.g. UTC, TAI,
UT1) and time representations (e.g. JD, MJD, ISO 8601) that are used in
astronomy.
"""

# units/quantity.py
"""
This module defines the `Quantity` object, which represents a number with some
associated units. `Quantity` objects support operations like ordinary numbers,
but will deal with unit conversions internally.
"""