8. Documentation
8.1. Introduction
.intro: This is the design of the documentation system for the Memory Pool System.
.readership: This document is intended for any MPS developer.
8.2. Types
.type: The MPS has multiple types of documentation, suitable for different audiences.
.type.comment: Comments in the code provide information that is required in order for developers to make correct edits to nearby code. (Audience: MPS developers editing nearby code.)
.type.design: Design documentation lists requirements and explains how the code meets the requirements. (Audience: MPS developers working on a subsystem.)
.type.devguide: Developer guides provide general guidance for developers, not specific to any particular subsystem. (Audience: MPS developers generally.)
.type.procedure: Procedures list the steps for carrying out development tasks. (Audience: MPS developers who need to carry out particular tasks reliably.)
.type.tutorial: Tutorials describe how to use the MPS to meet client program requirements. (Audience: beginner client program developers.)
.type.reference: Reference documentation specifies the public features of the MPS. (Audience: expert client program developers.)
.type.mmref: The Memory Management Reference describes general principles of memory management, with cross-references to the MPS documentation. (Audience: the world.)
8.3. Requirements
.req.source: Derived from [RB_2013-05-09].
.req.easy: It must be easy to read and write documentation using standard text editors. Barriers to documentation must be low.
.req.presentation: It must be possible to process documentation into presentation formats, for example web pages.
.req.single-source: Documents must have a single source. Processing into other formats must be automatic and not depend on hand editing or maintaining parallel versions.
.req.durable: The format of documents should be supported for the foreseeable future. It must not require continual updating to keep up with changes to processing software.
.req.design.ref: It must be easy to reference points made in design documents from the code.
.req.design.standalone: Design documents must stand alone: they must not require particular software to make them readable or complete.
8.4. Implementation
.impl.rst: Documents are written in reStructuredText (RST).
.impl.design: Design documents are written in plain RST (with no custom directives) to meet .req.design.standalone.
.impl.design.pelican: Design documents are converted to HTML using
pelican.readers.RstReader as part of Charlotte.
.impl.design.github: Design documents are also rendered as HTML by GitHub.
.impl.manual: The manual is written in RST using Sphinx extensions and custom manual extensions (see .ext).
.impl.manual.sphinx: The manual is converted to HTML using the Sphinx documentation generator.
.impl.manual.design: Design documents are automatically processed for inclusion in the manual using a set of formatting conventions (see .fmt).
8.5. Manual extensions
.ext: These are reStructuredText directives and roles used by the MPS manual. See manual/source/extensions/mps/__init__.py.
.ext.aka: The aka directive generates an “Also known as”
section. This should be used in a glossary entry, and should contain a
comma-separated, alphabetically ordered, list of glossary entries (in
italics) that are synonyms for this glossary entry.
.ext.bibref: The bibref directive generates a “Related
publication” or “Related publications” section. This should be used in
a glossary entry, and should contain a comma-separated, alphabetically
ordered, list of :ref: roles referring to entries in the
bibliography.
.ext.deprecated: The deprecated directive generates a
“Deprecated” section. It should be used in a description of a public
interface in the MPS Reference, and describe the first version in
which the interface was deprecated, and the interface that should be
used instead. There may be an initial “starting with version 1.115”
paragraph, but this is unnecessary if the directive is used in the
“Deprecated interfaces” chapter.
.ext.historical: The historical directive generates a
“Historical note” section. This should be used in a glossary entry,
and should contain material of historical interest, for example the
origin of the term, or ways in which it was formerly used.
.ext.link: The link directive generates a “Related link” or
“Related links” section. This should be used in a glossary entry, and
should contain a comma-separated list of references to URLs.
.ext.note: The note directive generates a “Note” or “Notes”
section. This should consist of a paragraph or a numbered list
containing especially important information about an interface that a
user should be aware of when using it.
.ext.opposite: The opposite directive generates an “Opposite
term” or “Opposite terms” section. This should be used in a glossary
entry, and should contain a comma-separated, alphabetically ordered,
list of :term: roles referring to glossary entries with opposite
meaning.
.ext.relevance: The relevance directive generates a “Relevance
to memory management” section. This should be used in a glossary
entry, and should contain an explanation of how the term relates to
memory management, if this is not obvious.
.ext.see: The see directive generates a “See” section. This
should be used in a glossary entry, and should contain a single
:term: role referring to the entry for which the currente entry is
a synonym.
.ext.seealso: The seealso directive generates a “See also”
section. This should be used in a glossary entry, and should contain a
comma-separated, alphabetically ordered, list of :term: roles
referring to glossary entries that relate to the entry but are neither
synonyms for it (.ext.aka), nor opposites (.ext.opposite), nor
similar (.ext.similar).
.ext.similar: The similar directive generates a “Similar term”
or “Similar terms” section. This should be used in a glossary entry,
and should contain a comma-separated, alphabetically ordered, list of
:term: roles referring to glossary entries with similar meaning to
the entry but which are not synonyms for it (.ext.aka).
.ext.specific: The mps:specific directive generates an “In the
MPS” section. This should be used in a glossary entry, and should
contain an explanation of how the glossary entry pertains to the MPS.
If the term is idiosyncratic to the MPS, for example “spare committed
memory” then the entire glossary entry should consist of a single
mps:specific directive to make it clear that the term is not in
general use.
8.6. Design formatting conventions
.fmt: This section lists formatting conventions used in the design documentation that are used to generate extended markup when the design document is converted for use in the MPS manual. See manual/source/extensions/mps/designs.py.
.fmt.function-decl: A paragraph consisting of a function declaration on a single line formatted as code, for example:
``void LandFinish(Land land)``
is translated into a c:function directive:
.. c:function:: void LandFinish(Land land)
.fmt.macro-decl: A paragraph consisting of a macro declaration on a single line formatted as code, for example:
``RING_FOR(node, ring, next)``
is translated into a c:macro directive:
.. c:macro:: RING_FOR(node, ring, next)
.fmt.macro: Macros are identified by having names consisting of
capital letters, numbers, and underscore, or appearing in the list of
exceptions given by the MACROS global in designs.py.
.fmt.type-def: A paragraph consisting of a type definition on a single line formatted as code, for example:
``typedef LandStruct *Land``
is translated into a c:type directive:
.. c:type:: LandStruct *Land
.fmt.function-ref: A word formatted as code and suffixed by (),
for example:
This saves a separate call to :c:func:`LandDelete()`, and uses the
knowledge of exactly where we found the range.
is translated into a :c:func: role:
This saves a separate call to :c:func:`LandDelete`, and uses the
knowledge of exactly where we found the range.
.fmt.type-ref: The name of an MPS type formatted as code, for example:
The function must return a :c:type:`Bool` indicating whether to continue
with the iteration.
is translated into a :c:type: role:
The function must return a :c:type:`Bool` indicating whether to
continue with the iteration.
The list of MPS types thus converted is given by the TYPES global
in designs.py, plus any word matching mps_[a-z_]+_[stu], plus any
word ending Class, Function, Method, Struct, or
Union.
.fmt.tag: A paragraph starting with an MPS tag, for example:
:mps:tag:`type.land` The type of a generic land instance.
is translated into an :mps:tag: role:
:mps:tag:`type.land` The type of a generic land instance.
.fmt.ref: Cross-references to tags, for example:
A *node* is used in the typical data structure sense to mean an
element of a tree (see also :mps:ref:`.type.tree`).
is translated into an :mps:ref: role:
A *node* is used in the typical data structure sense to mean an
element of a tree (see also :mps:ref:`.type.tree`).
.fmt.history: The section “Document History” is removed.
.fmt.copyright: The section “Copyright and License” is removed.
.fmt.sections: Section numbers are removed.
.fmt.metadata: Metadata roles are removed, except for:
.fmt.metadata.tag: :Tag:, which is translated into an
mps:prefix directive; and
.fmt.metadata.index: :Index Terms:, which is is translated into
an index directive.
.fmt.citation: Citations are translated from design style:
[Citation] "Title"; Author; Date; <URL>.
into manual style:
[Citation] Author. Date. "`Title <URL>`__".
.fmt.link.relative: Project-relative links must be specified using
named hyperlink targets whose targets start with ../, for
example:
``#ifdefs``, such as in mps.c_.
.. _mps.c: ../../../code/mps.c
The target is adjusted to reflect the different location of the manual sources relative to the design sources.
8.7. References
Richard Brooksby. Ravenbrook Limited. 2013-05-09. “MPS design document format and process”.