how_to_document¶
Writing documentation
Synopsis¶
Declared in <src/docs/mrdocs/rose/how_to_document.h>
struct how_to_document; Description¶
How to write API and non-API documentation in REX.
This chapter covers documentation for the REX library. Its style guidance applies to API comments and versioned project pages.
REX uses MrDocs for two broad categories of documentation:
- For documenting the REX API. MrDocs generates the structure of the documentation, and authors fill in the descriptions.
- For documenting non-API things that are nonetheless tied to a particular version of REX, such as this page.
Both categories of documentation (API and non-API) are written as comments in C++ source code and follow the same style conventions.
- Comment style: Whether to use block- or line-style comments is up to the author. However, authors are encouraged to use block style comments for documentation and line-style comments for non-documentation so that IDEs can easily highlight them differently. Furthermore, a vertical line of
*down the left side of block comments has two useful benefits: it helps those developers that don't use syntax-highlighting IDEs to realize that lines are part of a comment, and it provides a hint that lines matched byrg-style searching are comments rather than code. Both become more important as the size of the block comment grows, especially if it contains lines that might look like code. - Use at-sign style: The at-sign (
@) style uses@rather than the backslash () to introduce directives. IDEs tend to have fewer problems recognizing the at-sign style due to its popularity and the fact that@is relatively uncommon in C++ code. - Explicit references: Although MrDocs can automatically create cross references to any word that looks like a symbol, using an explicit
@refwill cause MrDocs to emit a warning if the referent's name changes and breaks the link. Our goal is to eventually fix all documentation warnings so that new warnings are easy to spot. - Capitalization: Use the Wikipedia style of capitalization for pages, sections, and subsections. Namely, the first word is capitalized and all other words except proper names and abbreviations are lower-case. Titles do not end with punctuation.
- "REX": Use the project's uppercase name when needed.
As mentioned, one of REX's uses of MrDocs is for documentation not related to any specific API element (such as this page itself). This section intends to show how to document such things.
Pages or modules? Non-API documentation is generally organized into pages and modules. Pages are relatively large chapter-like things, while modules are smaller (usually) and hierarchical. The distinction is blurry though because both support sections and subsections. Use this table to help decide:
| Use pages | Use modules | | --- | --- | | Subject is important enough to be a chapter in a book? | Subject would be an appendix in a book? | | Subject should be listed in the top-level table of contents? | Subject should be listed in some broader subject's page? | | User would read the entire subject linearly? | User would jump around in the subject area? | | Subject has two levels of nesting? | Subject has arbitrarily deep hierarchy? | | Subject's sections should appear together in a single HTML page? | Subject's sections should each be on their own HTML page? |
Pages and modules are represented by doc-only headers under src/docs/mrdocs. Each page or module is a dummy struct with a documentation block. The first sentence is the auto-brief content that shows up in tables of contents. The auto-brief sentence should fit on one line, end with a period, and should not be identical to the title; it should restate the title in different words or else the table of contents looks awkward.
Location of documentation source? Regardless of whether one chooses to write a page or a module, the documentation needs to be placed in a C++ header. These files should live under src/docs/mrdocs and be added to src/docs/mrdocs/doc_prelude.h so they are force-included during documentation builds. The MrDocs configuration file is docs/mrdocs.yml.
The original purpose of API documentation is to describe the files, namespaces, classes, functions, and other types that compose an API. MrDocs automatically generates the document structure from C++ declarations and the API author fills in those things that cannot be done automatically, which is the majority of the text. The bullets below reference this declaration:
`cpp public: std::vector<std::string> splitString(const std::string &inputString, const std::string &separator); `
- Co-location: The documentation comment should be adjacent to the thing it documents. Some people claim this unnecessarily clutters the header file and that the comment should be in a separate file, but the counter argument is that by having documentation near the declaration it is more likely to be updated if the declaration changes. Also, the cluttering-up claim is made moot by any reasonably capable IDE, especially if we separate API and implementation documentation by using C-style block comments for one and C++ line comments for the other.
- Auto brief: The documentation configuration is set up so that the first sentence of documentation gets used as the brief value without having to specify
@brief. The brief content should be concise. In particular, it should not start with "This function..." (since context provides that), it should easily fit on one line, it should not repeat information obvious from the declaration, and it should end with a period. Example: "Splits a string into substrings according to separator strings." - Public versus private: Every public and protected part of the API must be documented. Documentation is as important as implementation; even so-called "self documenting" practices need additional human-written descriptions to make them useful to users that might not be familiar with a certain technique or algorithm. If some entity is not documented then it is not worthy of being a member of the API. Eventually we will disable the switches that allow stub documentation for non-documented parts of the API. The private things should not be documented because if someone's using these they need to be reading the source anyway.
- Description: All API entities must have a clear description except if the auto-brief statement together with the declaration entirely captures all details of interest to a user, which is seldom the case. The description should describe any pre and post conditions, what happens if an error is detected, and provide an example directly or indirectly if appropriate. Type information need not be repeated since it's already documented in the declaration. Example: "The
@p inputStringis scanned to find each non-overlapping occurrence of the@p separatorstring from left to right. The substrings between the identified separators are returned in the order they occur, including empty substrings. If no separator is found in the input string then only the input string is returned, even if it is empty." - Function parameters: Function parameters need to be documented when their type and/or name is not sufficient. They can be documented in list format or as part of the function's description. Use the
@pformatting tag when referring to a parameter. It may work better to document related parameters in a descriptive paragraph than listing each one separately. If using a list, there's no need to include a parameter if the parameter is sufficiently documented in the main description or by the declaration; combine closely related parameters into a single item; attempt to minimize forward references by rewording or reordering. - To-do lists: If you need to mark documentation that should be fixed, use the
@todotag and include a description of what needs to be fixed. Also include your name (i.e., the person who thinks there's a problem) and the date. - Author name: Use revision history instead of author annotations.
- Proofread: Proofread your documentation in a web browser after MrDocs runs. One common error is for MrDocs to make a link to a capitalized word (like Function, at least as this is being written) that happens to also be an entity in the API. Prefix such words with a percent sign when the link is unintended. Likewise, authors should try to avoid class and namespace names that are also common words in order to prevent MrDocs from suddenly making those words links throughout all documentation. The documentation is generated by running
scripts/generate-api-documentationor by invokingscripts/build-docsto build the full site.
AST nodes (e.g. SgNode) are a special case because they are generated by ROSETTA, a code generator. So we can't document them inside the generated code. Instead we maintain documentation for AST nodes in doc-only headers and inject them into the doc build through src/docs/mrdocs/ast_node_docs.h.
MrDocs understands a subset of HTML, its own command directives, and Markdown. The most useful are:
- Sections and subsections are introduced by
@sectionor@subsectionfollowed by a unique identifier followed by the name of the section using Title capitalization described above. - Function parameter names are indicated with
@pfollowed by the parameter name. This typesets them in a consistent style. - References to other symbols, pages, and modules are indicated with
@reffollowed by the name or ID. The look-up for symbols is similar to how the C++ compiler would look up the name, so you might need to qualify it with some namespace or even place the comment inside a namespace. - Code snippets are indicated by preceding the word with
@c. If more than one word or if it contains special characters, use backticks instead. - To include an entire example source file into the documentation, use the
@snippetdirective and add a snippet tag around the whole file. The@snippetdirective takes two arguments: the name of an example source file, and the name of a snippet. The beginning and end of the snippet is marked in the source file using comments of the form//! [snippet name goes in here]. Snippet names can include space characters. - To document a namespace, class, function, variable, etc., place the documentation immediately prior to the declaration and use a block style comment. For variables and enum constants, a trailing documentation comment can be more convenient.
To generate REX's documentation locally, run:
scripts/generate-api-documentation(MrDocs only)scripts/build-docs(MrDocs + Zensical site)
MrDocs is documented at https://github.com/cppalliance/mrdocs.
See developer_docs.
Created with MrDocs