Documentation

A piece of documentation describing one property of a thing, be it a name or description of a contract, or an error throwable by given endpoint.

Items of the same type appear close to each other in a rendered documentation and form a section.

Doc items are later injected into a contract code via a dedicated nop-like instruction. Normally doc items which belong to one section appear in resulting doc in the same order in which they appeared in the contract.

While documentation framework grows, this typeclass acquires more and more methods for fine tuning of existing rendering logic because we don't want to break backward compatibility, hope one day we will make everything concise :( E.g. all rendering and reording stuff could be merged in one method, and we could have several template implementations for it which would allow user to specify only stuff relevant to his case.

Get doc item position at term-level.

Some unique identifier of a doc item.

All doc items which should be refer-able need to have this identifier.

Where do we place given doc item.

Position of all doc items of some type.

Type-level check whether or not a doc item can be referenced.

How to render section name.

Hides some documentation item.

Hides some documentation item which is put to "definitions" section.

A doc item which we store, along with related information.

Several doc items of the same type.

A map from positions to document elements.

This form effeciently keeps documentation for its incremental building. Doc items here appear close to how they were located in the contract; for instance, docItemsOrder is not yet applied at this stage. You only can be sure that items within each group are splitted across sections correctly.

A part of documentation to be grouped. Essentially incapsulates DocBlock.

Keeps documentation gathered for some piece of contract code.

Used for building documentation of a contract.

A function which groups a piece of doc under one doc item.

Whether given DocElem is atomic.

Normally, atomic DocElems are ones appearing in DOC_ITEM instruction, and non-atomic ones are put to DocGroup.

Render documentation for SubDoc.

Lift an atomic doc item to a block.

Reference to the given section.

Will return Nothing if sections of given doc item type are not assumed to be referred outside.

Find all doc items of the given type.

Render given contract documentation to markdown document.

Apply given grouping to documentation being built.

Make a reference to doc item in definitions.

Generate DToc entry anchor from docItemRef.

Often there is some tuning recommended prior to rendering the contract, like attaching git revision info; this type designates that those last changes were applied.

For example, at Michelson level you may want to use attachDocCommons.

If you want no special tuning (e.g. for tests), say that explicitly with finalizedAsIs.

Mark the code with doc as finalized without any changes.

Everything that contains doc items that can be used to render the documentation.

Some contract languages may support documentation update.

Gather documenation.

Construct and format documentation in textual form.

Recursevly traverse doc items and modify those that match given type.

If mapper returns Nothing, doc item will remain unmodified.

General (meta-)information about the contract such as git revision, contract's authors, etc. Should be relatively short (not several pages) because it is put somewhere close to the beginning of documentation.

Give a name to document block.

Description of something.

Repository settings for DGitRevision.

Make DGitRevision.

>>> :t $mkDGitRevision
GitRepoSettings -> DGitRevision

Comment in the doc (mostly used for licenses)

A hand-made anchor.

Table of contents to be inserted into the doc in an ad-hoc way.

It is not intended to be inserted manually. See attachToc to understand how this works.

Attach information about git revision. The code must contain git revision placeholder.

We do this in two stages because we use TH to deduce git revision information at compile time, and this is best to be done in the very end to recompile less modules.

Attach common information that is available only in the end.