Lorentz.Entrypoints.Doc

Utilities for declaring and documenting entry points.

Documentation

data DEntrypoint (kind :: Type)

Gathers information about single entrypoint.

We assume that entry points might be of different kinds, which is designated by phantom type parameter. For instance, you may want to have several groups of entry points corresponding to various parts of a contract - specifying different kind type argument for each of those groups will allow you defining different DocItem instances with appropriate custom descriptions for them.

Constructors

DEntrypoint

Fields

• depName :: Text
• depSub :: SubDoc

Instances

EntrypointKindHasDoc ep => DocItem (DEntrypoint ep)

Defined in Lorentz.Entrypoints.Doc

Associated Types

type DocItemPlacement (DEntrypoint ep) :: DocItemPlacementKind

type DocItemReferenced (DEntrypoint ep) :: DocItemReferencedKind

Methods

docItemPos :: Natural

docItemSectionName :: Maybe Text

docItemSectionDescription :: Maybe Markdown

docItemSectionNameStyle :: DocSectionNameStyle

docItemRef :: DEntrypoint ep -> DocItemRef (DocItemPlacement (DEntrypoint ep)) (DocItemReferenced (DEntrypoint ep))

docItemToMarkdown :: HeaderLevel -> DEntrypoint ep -> Markdown

docItemToToc :: HeaderLevel -> DEntrypoint ep -> Markdown

docItemDependencies :: DEntrypoint ep -> [SomeDocDefinitionItem]

docItemsOrder :: [DEntrypoint ep] -> [DEntrypoint ep]

type DocItemPlacement (DEntrypoint ep)

Defined in Lorentz.Entrypoints.Doc

type DocItemPlacement (DEntrypoint ep) = 'DocItemInlined

type DocItemReferenced (DEntrypoint ep)

Defined in Lorentz.Entrypoints.Doc

type DocItemReferenced (DEntrypoint ep) = 'True

pattern DEntrypointDocItem :: DEntrypoint kind -> SomeDocItem

Pattern that checks whether given SomeDocItem hides DEntrypoint inside (of any entrypoint kind).

In case a specific kind is necessary, use plain (cast -> Just DEntrypoint{..}) construction instead.

class Typeable ep => EntrypointKindHasDoc (ep :: Type) where

Describes location of entrypoints of the given kind.

All such entrypoints will be placed under the same "entrypoints" section, and this instance defines characteristics of this section.

Minimal complete definition

entrypointKindPos, entrypointKindSectionName

Methods

entrypointKindPos :: Natural

Position of the respective entrypoints section in the doc. This shares the same positions space with all other doc items.

entrypointKindSectionName :: Text

Name of the respective entrypoints section.

entrypointKindSectionDescription :: Maybe Markdown

Description in the respective entrypoints section.

Instances

EntrypointKindHasDoc CommonContractBehaviourKind

Defined in Lorentz.Entrypoints.Doc

Methods

entrypointKindPos :: Natural

entrypointKindSectionName :: Text

entrypointKindSectionDescription :: Maybe Markdown

EntrypointKindHasDoc PlainEntrypointsKind

Defined in Lorentz.Entrypoints.Doc

Methods

entrypointKindPos :: Natural

entrypointKindSectionName :: Text

entrypointKindSectionDescription :: Maybe Markdown

EntrypointKindHasDoc kind => EntrypointKindHasDoc (CommonEntrypointsBehaviourKind kind)

Defined in Lorentz.Entrypoints.Doc

Methods

entrypointKindPos :: Natural

entrypointKindSectionName :: Text

entrypointKindSectionDescription :: Maybe Markdown

entrypointSection :: EntrypointKindHasDoc kind => Text -> Proxy kind -> (i :-> o) -> i :-> o

Mark code as part of entrypoint with given name.

This is automatically called at most of the appropriate situations, like entryCase calls.

data DEntrypointReference

Inserts a reference to an existing entrypoint.

This helps to avoid duplication in the generated documentation, in order not to overwhelm the reader.

Constructors

DEntrypointReference Text Anchor

Instances

DocItem DEntrypointReference

Defined in Lorentz.Entrypoints.Doc

Associated Types

type DocItemPlacement DEntrypointReference :: DocItemPlacementKind

type DocItemReferenced DEntrypointReference :: DocItemReferencedKind

Methods

docItemPos :: Natural

docItemSectionName :: Maybe Text

docItemSectionDescription :: Maybe Markdown

docItemSectionNameStyle :: DocSectionNameStyle

docItemRef :: DEntrypointReference -> DocItemRef (DocItemPlacement DEntrypointReference) (DocItemReferenced DEntrypointReference)

docItemToMarkdown :: HeaderLevel -> DEntrypointReference -> Markdown

docItemToToc :: HeaderLevel -> DEntrypointReference -> Markdown

docItemDependencies :: DEntrypointReference -> [SomeDocDefinitionItem]

docItemsOrder :: [DEntrypointReference] -> [DEntrypointReference]

type DocItemPlacement DEntrypointReference

Defined in Lorentz.Entrypoints.Doc

type DocItemPlacement DEntrypointReference = 'DocItemInlined

type DocItemReferenced DEntrypointReference

Defined in Lorentz.Entrypoints.Doc

type DocItemReferenced DEntrypointReference = 'False

class EntryArrow kind name body where

Provides arror for convenient entrypoint documentation

Methods

(#->) :: (Label name, Proxy kind) -> body -> body

Lift entrypoint implementation.

Entrypoint names should go with "e" prefix.

Instances

(name ~ AppendSymbol "e" epName, body ~ ((param ': s) :-> out), KnownSymbol epName, DocItem (DEntrypoint kind), NiceParameter param, TypeHasDoc param, KnownValue param) => EntryArrow (kind :: Type) name body

Defined in Lorentz.Entrypoints.Doc

Methods

(#->) :: (Label name, Proxy kind) -> body -> body

data PlainEntrypointsKind

Default value for DEntrypoint type argument.

Instances

EntrypointKindHasDoc PlainEntrypointsKind

Defined in Lorentz.Entrypoints.Doc

Methods

entrypointKindPos :: Natural

entrypointKindSectionName :: Text

entrypointKindSectionDescription :: Maybe Markdown

data CommonContractBehaviourKind

Describes the behaviour common for all entrypoints.

For instance, if your contract runs some checks before calling any entrypoint, you probably want to wrap those checks into entrypointSection "Prior checks" (Proxy @CommonContractBehaviourKind).

Instances

EntrypointKindHasDoc CommonContractBehaviourKind

Defined in Lorentz.Entrypoints.Doc

Methods

entrypointKindPos :: Natural

entrypointKindSectionName :: Text

entrypointKindSectionDescription :: Maybe Markdown

data CommonEntrypointsBehaviourKind kind

Describes the behaviour common for entrypoints of given kind.

This has very special use cases, like contracts with mix of upgradeable and permanent entrypoints.

Instances

EntrypointKindHasDoc kind => EntrypointKindHasDoc (CommonEntrypointsBehaviourKind kind)

Defined in Lorentz.Entrypoints.Doc

Methods

entrypointKindPos :: Natural

entrypointKindSectionName :: Text

entrypointKindSectionDescription :: Maybe Markdown

diEntrypointToMarkdown :: HeaderLevel -> DEntrypoint level -> Markdown

Default implementation of docItemToMarkdown for entrypoints.

data SomeEntrypointArg

Entrypoint argument type in typed representation.

Constructors

forall a.(NiceParameter a, TypeHasDoc a) => SomeEntrypointArg (Proxy a)

data DEntrypointArg

Describes argument of an entrypoint.

Constructors

DEntrypointArg

Fields

• epaArg :: Maybe SomeEntrypointArg

  Argument of the entrypoint. Pass Nothing if no argument is required.

• epaBuilding :: [ParamBuildingStep]

  Describes a way to lift an entrypoint argument into full parameter which can be passed to the contract.

  Steps are supposed to be applied in the order opposite to one in which they are given. E.g. suppose that an entrypoint is called as Run (Service1 arg); then the first step (actual last) should describe wrapping into Run constructor, and the second step (actual first) should be about wrapping into Service1 constructor.

Instances

DocItem DEntrypointArg

Defined in Lorentz.Entrypoints.Doc

Associated Types

type DocItemPlacement DEntrypointArg :: DocItemPlacementKind

type DocItemReferenced DEntrypointArg :: DocItemReferencedKind

Methods

docItemPos :: Natural

docItemSectionName :: Maybe Text

docItemSectionDescription :: Maybe Markdown

docItemSectionNameStyle :: DocSectionNameStyle

docItemRef :: DEntrypointArg -> DocItemRef (DocItemPlacement DEntrypointArg) (DocItemReferenced DEntrypointArg)

docItemToMarkdown :: HeaderLevel -> DEntrypointArg -> Markdown

docItemToToc :: HeaderLevel -> DEntrypointArg -> Markdown

docItemDependencies :: DEntrypointArg -> [SomeDocDefinitionItem]

docItemsOrder :: [DEntrypointArg] -> [DEntrypointArg]

type DocItemPlacement DEntrypointArg

Defined in Lorentz.Entrypoints.Doc

type DocItemPlacement DEntrypointArg = 'DocItemInlined

type DocItemReferenced DEntrypointArg

Defined in Lorentz.Entrypoints.Doc

type DocItemReferenced DEntrypointArg = 'False

data DType where

Constructors

DType :: forall a. TypeHasDoc a => Proxy a -> DType

Instances

Eq DType

Defined in Michelson.Typed.Haskell.Doc

Methods

(==) :: DType -> DType -> Bool

(/=) :: DType -> DType -> Bool

Ord DType

Defined in Michelson.Typed.Haskell.Doc

Methods

compare :: DType -> DType -> Ordering

(<) :: DType -> DType -> Bool

(<=) :: DType -> DType -> Bool

(>) :: DType -> DType -> Bool

(>=) :: DType -> DType -> Bool

max :: DType -> DType -> DType

min :: DType -> DType -> DType

Show DType

Defined in Michelson.Typed.Haskell.Doc

Methods

showsPrec :: Int -> DType -> ShowS

show :: DType -> String

showList :: [DType] -> ShowS

DocItem DType

Defined in Michelson.Typed.Haskell.Doc

Associated Types

type DocItemPlacement DType :: DocItemPlacementKind

type DocItemReferenced DType :: DocItemReferencedKind

Methods

docItemPos :: Natural

docItemSectionName :: Maybe Text

docItemSectionDescription :: Maybe Markdown

docItemSectionNameStyle :: DocSectionNameStyle

docItemRef :: DType -> DocItemRef (DocItemPlacement DType) (DocItemReferenced DType)

docItemToMarkdown :: HeaderLevel -> DType -> Markdown

docItemToToc :: HeaderLevel -> DType -> Markdown

docItemDependencies :: DType -> [SomeDocDefinitionItem]

docItemsOrder :: [DType] -> [DType]

type DocItemPlacement DType

Defined in Michelson.Typed.Haskell.Doc

type DocItemPlacement DType = 'DocItemInDefinitions

type DocItemReferenced DType

Defined in Michelson.Typed.Haskell.Doc

type DocItemReferenced DType = 'True

class KnownSymbol con => DeriveCtorFieldDoc con (cf :: CtorField) where

Pick a type documentation from CtorField.

Methods

deriveCtorFieldDoc :: DEntrypointArg

Instances

KnownSymbol con => DeriveCtorFieldDoc con 'NoFields

Defined in Lorentz.Entrypoints.Doc

Methods

deriveCtorFieldDoc :: DEntrypointArg

(NiceParameter ty, TypeHasDoc ty, KnownValue ty, KnownSymbol con) => DeriveCtorFieldDoc con ('OneField ty)

Defined in Lorentz.Entrypoints.Doc

Methods

deriveCtorFieldDoc :: DEntrypointArg

newtype ParamBuilder

When describing the way of parameter construction - piece of incremental builder for this description.

Constructors

ParamBuilder

Fields

• unParamBuilder :: Markdown -> Markdown

  Argument stands for previously constructed parameter piece, and returned value - a piece constructed after our step.

Instances

Eq ParamBuilder

Defined in Lorentz.Entrypoints.Doc

Methods

(==) :: ParamBuilder -> ParamBuilder -> Bool

(/=) :: ParamBuilder -> ParamBuilder -> Bool

Show ParamBuilder

Defined in Lorentz.Entrypoints.Doc

Methods

showsPrec :: Int -> ParamBuilder -> ShowS

show :: ParamBuilder -> String

showList :: [ParamBuilder] -> ShowS

Buildable ParamBuilder

Defined in Lorentz.Entrypoints.Doc

Methods

build :: ParamBuilder -> Builder

data ParamBuildingDesc

Constructors

ParamBuildingDesc

Fields

• pbdEnglish :: Markdown

  Plain english description of this step.

• pbdHaskell :: ParamBuilder

  How to construct parameter in Haskell code.

• pbdMichelson :: ParamBuilder

  How to construct parameter working on raw Michelson.

Instances

Eq ParamBuildingDesc

Defined in Lorentz.Entrypoints.Doc

Methods

(==) :: ParamBuildingDesc -> ParamBuildingDesc -> Bool

(/=) :: ParamBuildingDesc -> ParamBuildingDesc -> Bool

Show ParamBuildingDesc

Defined in Lorentz.Entrypoints.Doc

Methods

showsPrec :: Int -> ParamBuildingDesc -> ShowS

show :: ParamBuildingDesc -> String

showList :: [ParamBuildingDesc] -> ShowS

data ParamBuildingStep

Describes a parameter building step.

This can be wrapping into (Haskell) constructor, or a more complex transformation.

Constructors

PbsWrapIn Text ParamBuildingDesc

Wraps something into constructor with given name. Constructor should be the one which corresponds to an entrypoint defined via field annotation, for more complex cases use PbsCustom.

PbsCallEntrypoint EpName

Directly call an entrypoint marked with a field annotation.

PbsCustom ParamBuildingDesc

Other action.

PbsUncallable [ParamBuildingStep]

This entrypoint cannot be called, which is possible when an explicit default entrypoint is present. This is not a true entrypoint but just some intermediate node in or tree and neither it nor any of its parents are marked with a field annotation.

It contains dummy ParamBuildingSteps which were assigned before entrypoints were taken into account.

Instances

Eq ParamBuildingStep

Defined in Lorentz.Entrypoints.Doc

Methods

(==) :: ParamBuildingStep -> ParamBuildingStep -> Bool

(/=) :: ParamBuildingStep -> ParamBuildingStep -> Bool

Show ParamBuildingStep

Defined in Lorentz.Entrypoints.Doc

Methods

showsPrec :: Int -> ParamBuildingStep -> ShowS

show :: ParamBuildingStep -> String

showList :: [ParamBuildingStep] -> ShowS

Buildable ParamBuildingStep

Defined in Lorentz.Entrypoints.Doc

Methods

build :: ParamBuildingStep -> Builder

mkPbsWrapIn :: Text -> ParamBuilder -> ParamBuildingStep

Make a ParamBuildingStep that tells about wrapping an argument into a constructor with given name and uses given ParamBuilder as description of Michelson part.

clarifyParamBuildingSteps :: ParamBuildingStep -> (inp :-> out) -> inp :-> out

Go over contract code and update every occurrence of DEntrypointArg documentation item, adding the given step to its "how to build parameter" description.

constructDEpArg :: forall arg. (NiceParameter arg, TypeHasDoc arg) => DEntrypointArg

emptyDEpArg :: DEntrypointArg

mkUType :: forall (x :: T). SingI x => Notes x -> Ty

mkDEpUType :: forall t. (KnownValue t, HasAnnotation t) => Ty

mkDEntrypointArgSimple :: forall t. (NiceParameter t, TypeHasDoc t) => DEntrypointArg

type DocumentEntrypoints kind a = (Generic a, GDocumentEntrypoints kind (Rep a))

Constraint for documentEntrypoints.

documentEntrypoint :: forall kind epName param s out. (KnownSymbol epName, DocItem (DEntrypoint kind), NiceParameter param, TypeHasDoc param) => ((param ': s) :-> out) -> (param ': s) :-> out

Wrapper for documenting single entrypoint which parameter isn't going to be unwrapped from some datatype.

entryCase unwraps a datatype, however, sometimes we want to have entrypoint parameter to be not wrapped into some datatype.

entryCase :: forall dt entrypointKind out inp clauses. (CaseTC dt out inp clauses, DocumentEntrypoints entrypointKind dt) => Proxy entrypointKind -> IsoRecTuple clauses -> (dt ': inp) :-> out

Version of entryCase_ for tuples.

entryCase_ :: forall dt entrypointKind out inp. (InstrCaseC dt, RMap (CaseClauses dt), DocumentEntrypoints entrypointKind dt) => Proxy entrypointKind -> Rec (CaseClauseL inp out) (CaseClauses dt) -> (dt ': inp) :-> out

Like case_, to be used for pattern-matching on a parameter or its part.

Modifies documentation accordingly. Including description of entrypoints' arguments, thus for them you will need to supply TypeHasDoc instance.

finalizeParamCallingDoc :: forall cp inp out. (NiceParameterFull cp, RequireSumType cp, HasCallStack) => ((cp ': inp) :-> out) -> (cp ': inp) :-> out

Version of 'finalizeParamCallingDoc'' more convenient for manual call in a contract.

finalizeParamCallingDoc' :: forall cp inp out. (NiceParameterFull cp, HasCallStack) => Proxy cp -> (inp :-> out) -> inp :-> out

Modify param building steps with respect to entrypoints that given parameter declares.

Each contract with entrypoints should eventually call this function, otherwise, in case if contract uses built-in entrypoints feature, the resulting parameter building steps in the generated documentation will not consider entrypoints and thus may be incorrect.

Calling this twice over the same code is also prohibited.

This method is for internal use, if you want to apply it to a contract manually, use finalizeParamCallingDoc.

areFinalizedParamBuildingSteps :: [ParamBuildingStep] -> Bool

Whether finalizeParamCallingDoc has already been applied to these steps.

entryCaseSimple_ :: forall cp out inp. (InstrCaseC cp, RMap (CaseClauses cp), DocumentEntrypoints PlainEntrypointsKind cp, RequireFlatParamEps cp) => Rec (CaseClauseL inp out) (CaseClauses cp) -> (cp ': inp) :-> out

entryCaseSimple :: forall cp out inp clauses. (CaseTC cp out inp clauses, DocumentEntrypoints PlainEntrypointsKind cp, RequireFlatParamEps cp) => IsoRecTuple clauses -> (cp ': inp) :-> out

Version of entryCase for contracts with flat parameter, use it when you need only one entryCase all over the contract implementation.

type family RequireFlatParamEps cp :: Constraint where ...

Equations

RequireFlatParamEps cp = (NiceParameterFull cp, RequireFlatEpDerivation cp (GetParameterEpDerivation cp), RequireSumType cp)

type family RequireFlatEpDerivation cp deriv :: Constraint where ...

Equations

RequireFlatEpDerivation _ EpdNone = ()

RequireFlatEpDerivation _ EpdPlain = ()

RequireFlatEpDerivation cp deriv = TypeError (('Text "Parameter is not flat" :$$: (('Text "For parameter `" :<>: 'ShowType cp) :<>: 'Text "`")) :$$: (('Text "With entrypoints derivation way `" :<>: 'ShowType deriv) :<>: 'Text "`"))