morley-1.12.0: Developer tools for the Michelson Language
Safe HaskellNone
LanguageHaskell2010

Michelson.Doc

Description

Renderable documentation injected to contract code.

Synopsis

Documentation

class (Typeable d, DOrd d) => DocItem d where Source #

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.

Minimal complete definition

docItemPos, docItemSectionName, docItemToMarkdown

Associated Types

type DocItemPlacement d :: DocItemPlacementKind Source #

Defines where given doc item should be put. There are two options: 1. Inline right here (default behaviour); 2. Put into definitions section.

Note that we require all doc items with "in definitions" placement to have Eq and Ord instances which comply the following law: if two documentation items describe the same entity or property, they should be considered equal.

type DocItemReferenced d :: DocItemReferencedKind Source #

Methods

docItemPos :: Natural Source #

Position of this item in the resulting documentation; the smaller the value, the higher the section with this element will be placed. If the position is the same as other doc items, they will be placed base on their name, alphabetically.

Documentation structure is not necessarily flat. If some doc item consolidates a whole documentation block within it, this block will have its own placement of items independent from outer parts of the doc.

docItemSectionName :: Maybe Text Source #

When multiple items of the same type belong to one section, how this section will be called.

If not provided, section will contain just untitled content.

docItemSectionDescription :: Maybe Markdown Source #

Description of a section.

Can be used to mention some common things about all elements of this section. Markdown syntax is permitted here.

docItemSectionNameStyle :: DocSectionNameStyle Source #

How to render section name.

Takes effect only if section name is set.

docItemRef :: d -> DocItemRef (DocItemPlacement d) (DocItemReferenced d) Source #

Defines a function which constructs an unique identifier of given doc item, if it has been decided to put the doc item into definitions section.

Identifier should be unique both among doc items of the same type and items of other types. Thus, consider using "typeId-contentId" pattern.

docItemToMarkdown :: HeaderLevel -> d -> Markdown Source #

Render given doc item to Markdown, preferably one line, optionally with header.

Accepts the smallest allowed level of header. (Using smaller value than provided one will interfere with existing headers thus delivering mess).

docItemToToc :: HeaderLevel -> d -> Markdown Source #

Render table of contents entry for given doc item to Markdown.

docItemDependencies :: d -> [SomeDocDefinitionItem] Source #

All doc items which this doc item refers to.

They will automatically be put to definitions as soon as given doc item is detected.

docItemsOrder :: [d] -> [d] Source #

This function accepts doc items put under the same section in the order in which they appeared in the contract and returns their new desired order. It's also fine to use this function for filtering or merging doc items.

Default implementation * leaves inlined items as is; * for items put to definitions, lexicographically sorts them by their id.

Instances

Instances details
DocItem DConversionInfo Source # 
Instance details

Defined in Michelson.Doc

DocItem DAnchor Source # 
Instance details

Defined in Michelson.Doc

DocItem DToc Source # 
Instance details

Defined in Michelson.Doc

DocItem DComment Source # 
Instance details

Defined in Michelson.Doc

DocItem DGitRevision Source # 
Instance details

Defined in Michelson.Doc

DocItem DDescription Source # 
Instance details

Defined in Michelson.Doc

DocItem DName Source # 
Instance details

Defined in Michelson.Doc

DocItem DGeneralInfoSection Source # 
Instance details

Defined in Michelson.Doc

DocItem DStorageType Source # 
Instance details

Defined in Michelson.Typed.Haskell.Doc

DocItem DType Source # 
Instance details

Defined in Michelson.Typed.Haskell.Doc

docItemPosition :: forall d. DocItem d => DocItemPos Source #

Get doc item position at term-level.

newtype DocItemId Source #

Some unique identifier of a doc item.

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

Constructors

DocItemId Text 

Instances

Instances details
Eq DocItemId Source # 
Instance details

Defined in Michelson.Doc

Ord DocItemId Source # 
Instance details

Defined in Michelson.Doc

Show DocItemId Source # 
Instance details

Defined in Michelson.Doc

ToAnchor DocItemId Source # 
Instance details

Defined in Michelson.Doc

data DocItemPlacementKind Source #

Where do we place given doc item.

Constructors

DocItemInlined

Placed in the document content itself.

DocItemInDefinitions

Placed in dedicated definitions section; can later be referenced.

newtype DocItemPos Source #

Position of all doc items of some type.

Constructors

DocItemPos (Natural, Text) 

Instances

Instances details
Eq DocItemPos Source # 
Instance details

Defined in Michelson.Doc

Ord DocItemPos Source # 
Instance details

Defined in Michelson.Doc

Show DocItemPos Source # 
Instance details

Defined in Michelson.Doc

Buildable DocItemPos Source # 
Instance details

Defined in Michelson.Doc

Methods

build :: DocItemPos -> Builder #

type DocItemReferencedKind = Bool Source #

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

data DocSectionNameStyle Source #

How to render section name.

Constructors

DocSectionNameBig

Suitable for block name.

DocSectionNameSmall

Suitable for subsection title within block.

data SomeDocItem where Source #

Hides some documentation item.

Constructors

SomeDocItem :: DocItem d => d -> SomeDocItem 

Instances

Instances details
Show SomeDocItem Source #

To automatically derive instance Show Michelson.Typed.Instr later.

Instance details

Defined in Michelson.Doc

Show DocGrouping Source # 
Instance details

Defined in Michelson.Doc

NFData SomeDocItem Source # 
Instance details

Defined in Michelson.Doc

Methods

rnf :: SomeDocItem -> () #

data DocElem d Source #

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

Constructors

DocElem 

Fields

data DocSection Source #

Several doc items of the same type.

Constructors

forall d.DocItem d => DocSection (NonEmpty $ DocElem d) 

Instances

Instances details
Show DocSection Source # 
Instance details

Defined in Michelson.Doc

type DocBlock = Map DocItemPos DocSection Source #

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.

newtype SubDoc Source #

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

Constructors

SubDoc DocBlock 

Instances

Instances details
Show DocGrouping Source # 
Instance details

Defined in Michelson.Doc

di ~ DName => IsString (SubDoc -> di) Source #

This instance allows writing something like docGroup Title, this makes sense as the most primitive and basic use case for doc groups is putting a section under name.

Instance details

Defined in Michelson.Doc

Methods

fromString :: String -> SubDoc -> di #

data ContractDoc Source #

Keeps documentation gathered for some piece of contract code.

Used for building documentation of a contract.

Constructors

ContractDoc 

Fields

  • cdContents :: DocBlock

    All inlined doc items.

  • cdDefinitions :: DocBlock

    Definitions used in document.

    Usually you put some large and repetitive descriptions here. This differs from the document content in that it contains sections which are always at top-level, disregard the nesting.

    All doc items which define docItemId method go here, and only they.

  • cdDefinitionsSet :: Set SomeDocDefinitionItem

    We remember all already declared entries to avoid cyclic dependencies in documentation items discovery.

  • cdDefinitionIds :: Set DocItemId

    We remember all already used identifiers. (Documentation naturally should not declare multiple items with the same identifier because that would make references to the respective anchors ambiguous).

Instances

Instances details
Semigroup ContractDoc Source #

Contract documentation assembly primarily relies on this instance.

Instance details

Defined in Michelson.Doc

Monoid ContractDoc Source # 
Instance details

Defined in Michelson.Doc

type DocGrouping = SubDoc -> SomeDocItem Source #

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

deIsAtomic :: DocElem d -> Bool Source #

Whether given DocElem is atomic.

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

subDocToMarkdown :: HeaderLevel -> SubDoc -> Markdown Source #

Render documentation for SubDoc.

docItemToBlock :: forall di. DocItem di => di -> DocBlock Source #

Lift an atomic doc item to a block.

docItemSectionRef :: forall di. DocItem di => Maybe Markdown Source #

Reference to the given section.

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

lookupDocBlockSection :: forall d. DocItem d => DocBlock -> Maybe (NonEmpty d) Source #

Find all doc items of the given type.

contractDocToMarkdown :: ContractDoc -> LText Source #

Render given contract documentation to markdown document.

docGroupContent :: DocGrouping -> ContractDoc -> ContractDoc Source #

Apply given grouping to documentation being built.

docDefinitionRef :: (DocItem d, DocItemPlacement d ~ 'DocItemInDefinitions) => Markdown -> d -> Markdown Source #

Make a reference to doc item in definitions.

mdTocFromRef :: (DocItem d, DocItemReferenced d ~ 'True) => HeaderLevel -> Markdown -> d -> Markdown Source #

Generate DToc entry anchor from docItemRef.

newtype WithFinalizedDoc a Source #

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.

Constructors

WithFinalizedDoc (Identity a) 

finalizedAsIs :: a -> WithFinalizedDoc a Source #

Mark the code with doc as finalized without any changes.

class ContainsDoc a where Source #

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

Methods

buildDocUnfinalized :: a -> ContractDoc Source #

Gather documentation.

Calling this method directly is discouraged in prod, see buildDoc instead. Using this method in tests is fine though.

Instances

Instances details
ContainsDoc (Instr inp out) Source # 
Instance details

Defined in Michelson.Typed.Doc

class ContainsDoc a => ContainsUpdateableDoc a where Source #

Some contract languages may support documentation update.

Methods

modifyDocEntirely :: (SomeDocItem -> SomeDocItem) -> a -> a Source #

Modify all documentation items recursively.

Instances

Instances details
ContainsUpdateableDoc (Instr inp out) Source # 
Instance details

Defined in Michelson.Typed.Doc

Methods

modifyDocEntirely :: (SomeDocItem -> SomeDocItem) -> Instr inp out -> Instr inp out Source #

buildDoc :: ContainsDoc a => WithFinalizedDoc a -> ContractDoc Source #

Gather documenation.

buildMarkdownDoc :: ContainsDoc a => WithFinalizedDoc a -> LText Source #

Construct and format documentation in textual form.

modifyDoc :: (ContainsUpdateableDoc a, DocItem i1, DocItem i2) => (i1 -> Maybe i2) -> a -> a Source #

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

If mapper returns Nothing, doc item will remain unmodified.

newtype GitRepoSettings Source #

Repository settings for DGitRevision.

Constructors

GitRepoSettings 

Fields

mkDGitRevision :: ExpQ Source #

Make DGitRevision.

>>> :t $mkDGitRevision
GitRepoSettings -> DGitRevision

data DToc Source #

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.

Constructors

DToc Markdown 

attachGitInfo :: ContainsUpdateableDoc a => DGitRevision -> a -> WithFinalizedDoc a Source #

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.

attachDocCommons :: ContainsUpdateableDoc a => DGitRevision -> a -> WithFinalizedDoc a Source #

Attach common information that is available only in the end.