Documentation

author Gareth Rees
date 2018-09-18
index terms pair: documentation; design
revision //info.ravenbrook.com/project/mps/master/design/doc.txt#13
status draft design
tag design.mps.doc

Introduction

.intro: This is the design of the documentation system for the Memory Pool System.

.readership: This document is intended for any MPS developer.

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.)

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.

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).

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.

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 ``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 ``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:

_`.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 `.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.

References

[RB_2013-05-09](1, 2) "MPS design document format and process"; Richard Brooksby; Ravenbrook Limited; 2013-05-09; <https://info.ravenbrook.com/mail/2013/05/09/14-54-55/0/>.

Document History