Documentation guidelines

From MCRL2

This page describes the documentation guidelines for tools and libraries.

Contents 1 Tools 1.1 User manual 2 Libraries 2.1 User manual 2.2 Reference manual 3 General 3.1 Acknowledgements

Tools

Tool documentation should consist of help information and a user manual. The help information is described in the tool interface guidelines, the user manual is described here.

User manual

The tool user manual should be available at the tool manual pages, and should be named after the tool. The page should contain a one-line description, and the following sections (in that order):

• Synopsis: the line

TOOL [OPTION]... ARGS

where:

• TOOL stands for the official name of the tool;
• ARGS stands for the arguments the tool can take, where optional arguments are typeset in square brackets '[' and ']'.

• Short description: a short explanation of the workings of the tool, including the effects on the arguments (not the options).
• Options: a list of all non-standard command line options. The list should be sorted alphabetically on short option, or long option when there is no short option. It should be formatted as follows:

OPTION can be any of the following:

-o, --option

description of the option

-oFOO, --option=FOO

description of the option and the possible values of mandatory argument FOO

-o[FOO], --option[=FOO]

description of the option and the possible values of optional argument FOO, including an indication of the default value

If a number of option descriptions consist of multiple sentences, it is also allowed to use full sentences (including capitals and full stops) in option descriptions.

Below the list of all non-standard options, the list of standard options should be printed as a separate paragraph, formatted as follows:

Standard options:

-q, --quiet

do not display warning messages

-v, --verbose

display short intermediate messages

-d, --debug

display detailed intermediate messages

-h, --help

display help information

--version

display version information

• Known issues (if any)
• See also (optional)
• References and acknowledgements (if needed)
• Detailed description (optional): a detailed explanation of the workings of the tool, including the effects of the options.
• Examples (optional)
• Authors: the line

Written by AUTHORS.

where AUTHORS stands for the names of the authors.

• Reporting bugs: the line

Report bugs at our issue tracking system.

Libraries

Library documentation should consist of a user manual and reference manual. Both should be available on the library documentation page.

User manual

The library user manual provides an informal explanation of the library and its use. It should consist of the following sections (in that order):

• Introduction
• Concepts
• Structure
• Tutorial
• References (if any)
• Acknowledgements (if needed)
• Authors: the line

Written by AUTHORS.

where AUTHORS stands for the names of the authors.

• Reporting bugs:

Report bugs at our issue tracking system.

Reference manual

The library reference manual provides a technical specification of the library. It should consist of an explanation of all used elements in the public interface. This manual should be automatically generated from the library code using Doxygen comments. The current convention is that only documented code will be displayed, unless the \internal command is included in the Doxygen comment. Library code located in a detail sub-directory is considered to be no part of the public interface, and no documentation is generated for this code.

Doxygen documentation should specified as follows:

• For each directory and file in the public interface, structural commands \dir and \file should be used.
• For each file member in the public interface, a special documentation block should be put directly above the file member. File members include, but are not limited to, namespaces, classes, structs, unions, enums, functions, variables, defines and typedefs.

In the above specified documentation, the following Doxygen special commands should be used:

• \brief: a one-line description for each directory, file, and file member in the public interface.
• \param: a parameter description for each parameter of a public function.
• \return: a return value description for each non-void public function.

There are instructions for building the reference manual for offline viewing.

General

The following documentation guidelines apply to both tools and libraries.

Acknowledgements

All tools and libraries should acknowledge authors of used or "inspirational" code. This does include but is certainly not limited to fulfilling license requirements. Acknowledgements are required in the following cases:

• The use of code - altered or not - of third parties.
• The use of algorithms, data structures, architectures etc. designed by third parties.
• The use of third-party code, tools, algorithms etc. as an inspirational basis.

However, things regarded as common knowledge are excluded from the latter two requirements.

Besides these requirements, authors of the mCRL2 toolset are highly encouraged to add references to related work (similar to adding related work in a paper).

Some examples to illustrate:

• Copying a snippet of code ad verbatim from outside the mCRL2 toolset requires acknowledgements.
• Modifying such a piece of code does not change this.
• Implementing quicksort does not require acknowledgements as it can be considered common knowledge. This does not include using a third-party implementation of quicksort; acknowledgements to the author of that implementation are required.
• Implementation of an algorithm found in an article should refer to that article.
• When implementing a tool with a similar third-party tool in mind, one should refer to that third-party tool as source of inspiration.

We distinguish three types of acknowledgements:

full 

This means that all relevant information should be given. That is, authors, articles, original source location and a description of the precise use of the code etc.

summary 

A summary of the information of full. This should include the authors, article name and functionality description.

short summary 

Even shorter variant of the summary. This should only include authors or article name and the functionality.

Some examples to illustrate:

• full: The following function is based on the algorithm in A.U. Thor, "Algorithms for Dummies", Publish Inc., 1975. I have changed the data structure a bit such that lookup is now O(log(n)) instead of O(n).
• summary: Shribbing functionality based on A.U. Thor, "Algorithms for Dummies".
• short summary: Algorithms for Dummies (shribbing)

Where to acknowledge and to what extent:

• Within a source file full acknowledgements should be added at relevant places. The only exception is a source file that as a whole is taken ad verbatim and already includes the relevant information (such as a license).
• Library documentation of functions should contain or refer to summary acknowledgements (but not to those within the source code itself). It is possible to group acknowledgements and put them all in one place as long as it is clear what the acknowledgements refer to.
• A library's user manual should contain summary acknowledgements.
• A tool's manual page should contain summary acknowledgements.
• When a tool's core functionality is part of a library and this part has acknowledgements, the tool itself should also acknowledge. This may be in a short form with a reference to the full(er) acknowledgement in the library. (For instance, when library X has function F with certain acknowledgements and one of the main tasks of a tool is to read a file apply F and return the result, then the tool should include the acknowledgements for F.)