Manual: doctools

Describes how the documentation tools work in Lever. Not complete or comprehensive description.

Lever's documentation tools supports an upwards workflow where the documentation follows the source code. This helps to ensure that the documentation is indeed accurate documentation and not merely good wishes.

Comprehensive and good documentation is a very different thing than the source code, therefore the source code and documentation remain in different files. The documentation is contained in the 'doc' -directory that is copied along into the runtime distribution.

The documentation is accessible to runtime, although the tools to retrieve and read documentation in REPL do not currently exist.

Documentation is written in texopic -language. The language is remotely similar with XML or HTML but has an exception that it differentiates between vertical and horizontal elements in the text. The details about the language will appear in the texopic module docs.

A single documentation file functions as both a manual and a reference. It is usable as both with searching, indexing and filtering tools.

The appropriate reference cards are pointed out by groups within the text. The cards contain lot of information that is treated appropriately.

The description of all fields is not completed.

Since Lever is a very amenable language for change it is important to communicate when things may change. Sometimes it may even require that we know how and why things change. For this reason we have a 'status/0' group separator that is present in all reference card groups.

If the status field is missing, it means that the details of the object described in the reference are highly stable. The changes of such function are only allowed after a major version change. Changes into such details may require a transition time to be scheduled.

The documentation generator automatically adds #status volatile into every reference card. This means that the author reserves the option to change the interface and that only the exact version or even an exact git commit is required for the program that uses this function.

Volatile status is meant for the situation where the status of a specific interface is not determined. Another status, internal, can be used to point out that the documented item is an internal implementation detail not meant for external use. Relying on such features require same measurements as if the status was 'volatile'.