Safe Haskell | None |
---|---|
Language | Haskell2010 |
Synopsis
- doc :: DocItem di => di -> s :-> s
- docGroup :: DocGrouping -> (inp :-> out) -> inp :-> out
- buildLorentzDoc :: (inp :-> out) -> ContractDoc
- renderLorentzDoc :: (inp :-> out) -> LText
- contractName :: Text -> (inp :-> out) -> inp :-> out
- cutLorentzNonDoc :: (inp :-> out) -> s :-> s
- type Markdown = Builder
- class (Typeable d, DOrd d, KnownNat (DocItemPosition d)) => DocItem d where
- type DocItemPosition d = (pos :: Nat) | pos -> d
- type DocItemPlacement d :: DocItemPlacementKind
- docItemSectionName :: Maybe Text
- docItemSectionDescription :: Maybe Markdown
- docItemSectionNameStyle :: DocSectionNameStyle
- docItemRef :: d -> DocItemRef (DocItemPlacement d)
- docItemToMarkdown :: HeaderLevel -> d -> Markdown
- docItemDependencies :: d -> [SomeDocDefinitionItem]
- docItemsOrder :: [d] -> [d]
- docItemPosition :: DocItem d => DocItemPos
- newtype DocItemId = DocItemId Text
- data DocItemPlacementKind
- data DocItemRef (p :: DocItemPlacementKind) where
- DocItemRef :: forall (p :: DocItemPlacementKind). DocItemId -> DocItemRef DocItemInDefinitions
- DocItemNoRef :: forall (p :: DocItemPlacementKind). DocItemRef DocItemInlined
- data DocSectionNameStyle
- data SomeDocItem where
- SomeDocItem :: forall d. DocItem d => d -> SomeDocItem
- data SomeDocDefinitionItem where
- SomeDocDefinitionItem :: forall d. (DocItem d, DocItemPlacement d ~ DocItemInDefinitions) => d -> SomeDocDefinitionItem
- newtype SubDoc = SubDoc DocBlock
- type DocGrouping = SubDoc -> SomeDocItem
- data ContractDoc = ContractDoc {}
- data DDescription = DDescription Markdown
- data DGitRevision
- = DGitRevisionKnown DGitRevisionInfo
- | DGitRevisionUnknown
- newtype GitRepoSettings = GitRepoSettings {
- grsMkGitRevision :: Text -> Text
- mkDGitRevision :: ExpQ
- morleyRepoSettings :: GitRepoSettings
- data DComment = DComment Text
- data DType where
- DType :: forall a. TypeHasDoc a => Proxy a -> DType
- docDefinitionRef :: (DocItem d, DocItemPlacement d ~ DocItemInDefinitions) => Markdown -> d -> Markdown
- contractDocToMarkdown :: ContractDoc -> LText
- subDocToMarkdown :: HeaderLevel -> SubDoc -> Markdown
- class Typeable a => TypeHasDoc a where
- typeDocName :: Proxy a -> Text
- typeDocMdDescription :: Markdown
- typeDocMdReference :: Proxy a -> WithinParens -> Markdown
- typeDocDependencies :: Proxy a -> [SomeTypeWithDoc]
- typeDocHaskellRep :: TypeDocHaskellRep a
- typeDocMichelsonRep :: TypeDocMichelsonRep a
- data SomeTypeWithDoc where
- SomeTypeWithDoc :: forall td. TypeHasDoc td => Proxy td -> SomeTypeWithDoc
- class HaveCommonTypeCtor (a :: k) (b :: k1)
- class IsHomomorphic (a :: k)
- genericTypeDocDependencies :: (Generic a, GTypeHasDoc (Rep a)) => Proxy a -> [SomeTypeWithDoc]
- customTypeDocMdReference :: (Text, DType) -> [DType] -> WithinParens -> Markdown
- homomorphicTypeDocMdReference :: (Typeable t, TypeHasDoc t, IsHomomorphic t) => Proxy t -> WithinParens -> Markdown
- poly1TypeDocMdReference :: (r ~ t a, Typeable t, Each (TypeHasDoc ': ([] :: [Type -> Constraint])) (r ': (a ': ([] :: [Type]))), IsHomomorphic t) => Proxy r -> WithinParens -> Markdown
- poly2TypeDocMdReference :: (r ~ t a b, Typeable t, Each (TypeHasDoc ': ([] :: [Type -> Constraint])) (r ': (a ': (b ': ([] :: [Type])))), IsHomomorphic t) => Proxy r -> WithinParens -> Markdown
- homomorphicTypeDocHaskellRep :: (Generic a, GTypeHasDoc (Rep a)) => TypeDocHaskellRep a
- concreteTypeDocHaskellRep :: (Typeable a, GenericIsoValue a, GTypeHasDoc (Rep a), HaveCommonTypeCtor b a) => TypeDocHaskellRep b
- concreteTypeDocHaskellRepUnsafe :: (Typeable a, GenericIsoValue a, GTypeHasDoc (Rep a)) => TypeDocHaskellRep b
- haskellRepNoFields :: TypeDocHaskellRep a -> TypeDocHaskellRep a
- haskellRepStripFieldPrefix :: HasCallStack => TypeDocHaskellRep a -> TypeDocHaskellRep a
- homomorphicTypeDocMichelsonRep :: SingI (ToT a) => TypeDocMichelsonRep a
- concreteTypeDocMichelsonRep :: (Typeable a, SingI (ToT a), HaveCommonTypeCtor b a) => TypeDocMichelsonRep b
- concreteTypeDocMichelsonRepUnsafe :: (Typeable a, SingI (ToT a)) => TypeDocMichelsonRep b
Documentation
docGroup :: DocGrouping -> (inp :-> out) -> inp :-> out Source #
Group documentation built in the given piece of code into block dedicated to one thing, e.g. to one entrypoint.
buildLorentzDoc :: (inp :-> out) -> ContractDoc Source #
renderLorentzDoc :: (inp :-> out) -> LText Source #
contractName :: Text -> (inp :-> out) -> inp :-> out Source #
Give a name to given contract. Apply it to the whole contract code.
cutLorentzNonDoc :: (inp :-> out) -> s :-> s Source #
Leave only instructions related to documentation.
This function is useful when your method executes a lambda coming from outside, but you know its properties and want to propagate its documentation to your contract code.
Re-exports
A piece of markdown document.
This is opposed to Text
type, which in turn is not supposed to contain
markup elements.
class (Typeable d, DOrd d, KnownNat (DocItemPosition d)) => DocItem d where #
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.
type DocItemPosition d = (pos :: Nat) | pos -> d #
Position of this item in the resulting documentation; the smaller the value, the higher the section with this element will be placed.
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.
type DocItemPlacement d :: DocItemPlacementKind #
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.
docItemSectionName :: Maybe Text #
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 #
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 #
How to render section name.
Takes effect only if section name is set.
docItemRef :: d -> DocItemRef (DocItemPlacement d) #
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 #
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).
docItemDependencies :: d -> [SomeDocDefinitionItem] #
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] #
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
docItemPosition :: DocItem d => DocItemPos #
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.
data DocItemPlacementKind #
Where do we place given doc item.
DocItemInlined | Placed in the document content itself. |
DocItemInDefinitions | Placed in dedicated definitions section; can later be referenced. |
data DocItemRef (p :: DocItemPlacementKind) where #
Defines an identifier which given doc item can be referenced with.
DocItemRef :: forall (p :: DocItemPlacementKind). DocItemId -> DocItemRef DocItemInDefinitions | |
DocItemNoRef :: forall (p :: DocItemPlacementKind). DocItemRef DocItemInlined |
data DocSectionNameStyle #
How to render section name.
DocSectionNameBig | Suitable for block name. |
DocSectionNameSmall | Suitable for subsection title within block. |
data SomeDocItem where #
Hides some documentation item.
SomeDocItem :: forall d. DocItem d => d -> SomeDocItem |
Instances
Show DocGrouping | |
Defined in Michelson.Doc showsPrec :: Int -> DocGrouping -> ShowS # show :: DocGrouping -> String # showList :: [DocGrouping] -> ShowS # | |
Show SomeDocItem | To automatically derive |
Defined in Michelson.Doc showsPrec :: Int -> SomeDocItem -> ShowS # show :: SomeDocItem -> String # showList :: [SomeDocItem] -> ShowS # |
data SomeDocDefinitionItem where #
Hides some documentation item which is put to "definitions" section.
SomeDocDefinitionItem :: forall d. (DocItem d, DocItemPlacement d ~ DocItemInDefinitions) => d -> SomeDocDefinitionItem |
Instances
Eq SomeDocDefinitionItem | |
Defined in Michelson.Doc (==) :: SomeDocDefinitionItem -> SomeDocDefinitionItem -> Bool # (/=) :: SomeDocDefinitionItem -> SomeDocDefinitionItem -> Bool # | |
Ord SomeDocDefinitionItem | |
Defined in Michelson.Doc compare :: SomeDocDefinitionItem -> SomeDocDefinitionItem -> Ordering # (<) :: SomeDocDefinitionItem -> SomeDocDefinitionItem -> Bool # (<=) :: SomeDocDefinitionItem -> SomeDocDefinitionItem -> Bool # (>) :: SomeDocDefinitionItem -> SomeDocDefinitionItem -> Bool # (>=) :: SomeDocDefinitionItem -> SomeDocDefinitionItem -> Bool # max :: SomeDocDefinitionItem -> SomeDocDefinitionItem -> SomeDocDefinitionItem # min :: SomeDocDefinitionItem -> SomeDocDefinitionItem -> SomeDocDefinitionItem # |
A part of documentation to be grouped. Essentially incapsulates DocBlock
.
Instances
Show DocGrouping | |
Defined in Michelson.Doc showsPrec :: Int -> DocGrouping -> ShowS # show :: DocGrouping -> String # showList :: [DocGrouping] -> ShowS # |
type DocGrouping = SubDoc -> SomeDocItem #
A function which groups a piece of doc under one doc item.
data ContractDoc #
Keeps documentation gathered for some piece of contract code.
Used for building documentation of a contract.
ContractDoc | |
|
Instances
Semigroup ContractDoc | Contract documentation assembly primarily relies on this instance. |
Defined in Michelson.Doc (<>) :: ContractDoc -> ContractDoc -> ContractDoc # sconcat :: NonEmpty ContractDoc -> ContractDoc # stimes :: Integral b => b -> ContractDoc -> ContractDoc # | |
Monoid ContractDoc | |
Defined in Michelson.Doc mempty :: ContractDoc # mappend :: ContractDoc -> ContractDoc -> ContractDoc # mconcat :: [ContractDoc] -> ContractDoc # |
data DDescription #
Description of something.
Instances
DocItem DDescription | |
Defined in Michelson.Doc type DocItemPosition DDescription = (pos :: Nat) # type DocItemPlacement DDescription :: DocItemPlacementKind # docItemSectionName :: Maybe Text # docItemSectionDescription :: Maybe Markdown # docItemSectionNameStyle :: DocSectionNameStyle # docItemRef :: DDescription -> DocItemRef (DocItemPlacement DDescription) # docItemToMarkdown :: HeaderLevel -> DDescription -> Markdown # docItemDependencies :: DDescription -> [SomeDocDefinitionItem] # docItemsOrder :: [DDescription] -> [DDescription] # | |
type DocItemPlacement DDescription | |
Defined in Michelson.Doc | |
type DocItemPosition DDescription | |
Defined in Michelson.Doc |
data DGitRevision #
DGitRevisionKnown DGitRevisionInfo | |
DGitRevisionUnknown |
Instances
DocItem DGitRevision | |
Defined in Michelson.Doc type DocItemPosition DGitRevision = (pos :: Nat) # type DocItemPlacement DGitRevision :: DocItemPlacementKind # docItemSectionName :: Maybe Text # docItemSectionDescription :: Maybe Markdown # docItemSectionNameStyle :: DocSectionNameStyle # docItemRef :: DGitRevision -> DocItemRef (DocItemPlacement DGitRevision) # docItemToMarkdown :: HeaderLevel -> DGitRevision -> Markdown # docItemDependencies :: DGitRevision -> [SomeDocDefinitionItem] # docItemsOrder :: [DGitRevision] -> [DGitRevision] # | |
type DocItemPlacement DGitRevision | |
Defined in Michelson.Doc | |
type DocItemPosition DGitRevision | |
Defined in Michelson.Doc |
newtype GitRepoSettings #
Repository settings for DGitRevision
.
GitRepoSettings | |
|
mkDGitRevision :: ExpQ #
Make DGitRevision
.
>>>
:t $mkDGitRevision
GitRepoSettings -> DGitRevision
Instances
DocItem DComment | |
Defined in Michelson.Doc type DocItemPosition DComment = (pos :: Nat) # docItemSectionName :: Maybe Text # docItemSectionDescription :: Maybe Markdown # docItemSectionNameStyle :: DocSectionNameStyle # docItemRef :: DComment -> DocItemRef (DocItemPlacement DComment) # docItemToMarkdown :: HeaderLevel -> DComment -> Markdown # docItemDependencies :: DComment -> [SomeDocDefinitionItem] # docItemsOrder :: [DComment] -> [DComment] # | |
type DocItemPlacement DComment | |
Defined in Michelson.Doc | |
type DocItemPosition DComment | |
Defined in Michelson.Doc |
Doc element with description of a type.
DType :: forall a. TypeHasDoc a => Proxy a -> DType |
Instances
Eq DType | |
Ord DType | |
Show DType | |
DocItem DType | |
Defined in Michelson.Typed.Haskell.Doc type DocItemPosition DType = (pos :: Nat) # type DocItemPlacement DType :: DocItemPlacementKind # docItemSectionName :: Maybe Text # docItemSectionDescription :: Maybe Markdown # docItemSectionNameStyle :: DocSectionNameStyle # docItemRef :: DType -> DocItemRef (DocItemPlacement DType) # docItemToMarkdown :: HeaderLevel -> DType -> Markdown # docItemDependencies :: DType -> [SomeDocDefinitionItem] # docItemsOrder :: [DType] -> [DType] # | |
type DocItemPlacement DType | |
Defined in Michelson.Typed.Haskell.Doc | |
type DocItemPosition DType | |
Defined in Michelson.Typed.Haskell.Doc |
docDefinitionRef :: (DocItem d, DocItemPlacement d ~ DocItemInDefinitions) => Markdown -> d -> Markdown #
Make a reference to doc item in definitions.
contractDocToMarkdown :: ContractDoc -> LText #
Render given contract documentation to markdown document.
subDocToMarkdown :: HeaderLevel -> SubDoc -> Markdown #
Render documentation for SubDoc
.
class Typeable a => TypeHasDoc a where #
Description for a Haskell type appearing in documentation.
typeDocName :: Proxy a -> Text #
Name of type as it appears in definitions section.
Each type must have its own unique name because it will be used in identifier for references.
Default definition derives name from Generics.
If it does not fit, consider defining this function manually.
(We tried using Data
for this, but it produces names including
module names which is not do we want).
typeDocMdDescription :: Markdown #
Explanation of a type. Markdown formatting is allowed.
typeDocMdReference :: Proxy a -> WithinParens -> Markdown #
How reference to this type is rendered, in Markdown.
Examples:
* Integer
,
* Maybe ()
.
Consider using one of the following functions as default implementation;
which one to use depends on number of type arguments in your type:
* homomorphicTypeDocMdReference
* poly1TypeDocMdReference
* poly2TypeDocMdReference
If none of them fits your purposes precisely, consider using
customTypeDocMdReference
.
typeDocDependencies :: Proxy a -> [SomeTypeWithDoc] #
All types which this type directly contains.
Used in automatic types discovery.
typeDocHaskellRep :: TypeDocHaskellRep a #
For complex types - their immediate Haskell representation.
For primitive types set this to Nothing
.
For homomorphic types use homomorphicTypeDocHaskellRep
implementation.
For polymorhpic types consider using concreteTypeDocHaskellRep
as implementation.
Modifier haskellRepNoFields
can be used to hide names of fields,
beneficial for newtypes.
Another modifier called haskellRepStripFieldPrefix
can be used for datatypes
to leave only meaningful part of name in every field.
typeDocMichelsonRep :: TypeDocMichelsonRep a #
Final michelson representation of a type.
For homomorphic types use homomorphicTypeDocMichelsonRep
implementation.
For polymorhpic types consider using concreteTypeDocMichelsonRep
as implementation.
Instances
data SomeTypeWithDoc where #
Data hides some type implementing TypeHasDoc
.
SomeTypeWithDoc :: forall td. TypeHasDoc td => Proxy td -> SomeTypeWithDoc |
class HaveCommonTypeCtor (a :: k) (b :: k1) #
Require two types to be built from the same type constructor.
E.g. HaveCommonTypeCtor (Maybe Integer) (Maybe Natural)
is defined,
while HaveCmmonTypeCtor (Maybe Integer) [Integer]
is not.
Instances
HaveCommonTypeCtor (a :: k) (a :: k) | |
Defined in Michelson.Typed.Haskell.Doc | |
HaveCommonTypeCtor ac bc => HaveCommonTypeCtor (ac a :: k4) (bc b :: k2) | |
Defined in Michelson.Typed.Haskell.Doc |
class IsHomomorphic (a :: k) #
Require this type to be homomorphic.
Instances
IsHomomorphic (a :: k) | |
Defined in Michelson.Typed.Haskell.Doc | |
(TypeError (Text "Type is not homomorphic: " :<>: ShowType (a b)) :: Constraint) => IsHomomorphic (a b :: k2) | |
Defined in Michelson.Typed.Haskell.Doc |
genericTypeDocDependencies :: (Generic a, GTypeHasDoc (Rep a)) => Proxy a -> [SomeTypeWithDoc] #
Implement typeDocDependencies
via getting all immediate fields
of a datatype.
Note: this will not include phantom types, I'm not sure yet how this scenario should be handled (@martoon).
customTypeDocMdReference :: (Text, DType) -> [DType] -> WithinParens -> Markdown #
Render a reference to a type which consists of type constructor (you have to provide name of this type constructor and documentation for the whole type) and zero or more type arguments.
homomorphicTypeDocMdReference :: (Typeable t, TypeHasDoc t, IsHomomorphic t) => Proxy t -> WithinParens -> Markdown #
Derive typeDocMdReference
, for homomorphic types only.
poly1TypeDocMdReference :: (r ~ t a, Typeable t, Each (TypeHasDoc ': ([] :: [Type -> Constraint])) (r ': (a ': ([] :: [Type]))), IsHomomorphic t) => Proxy r -> WithinParens -> Markdown #
Derive typeDocMdReference
, for polymorphic type with one
type argument, like Maybe Integer
.
poly2TypeDocMdReference :: (r ~ t a b, Typeable t, Each (TypeHasDoc ': ([] :: [Type -> Constraint])) (r ': (a ': (b ': ([] :: [Type])))), IsHomomorphic t) => Proxy r -> WithinParens -> Markdown #
Derive typeDocMdReference
, for polymorphic type with two
type arguments, like Lambda Integer Natural
.
homomorphicTypeDocHaskellRep :: (Generic a, GTypeHasDoc (Rep a)) => TypeDocHaskellRep a #
Implement typeDocHaskellRep
for a homomorphic type.
Note that it does not require your type to be of IsHomomorphic
instance,
which can be useful for some polymorhpic types which, for documentation
purposes, we want to consider homomorphic.
Example: Operation
is in fact polymorhpic, but we don't want this fact to
be reflected in the documentation.
concreteTypeDocHaskellRep :: (Typeable a, GenericIsoValue a, GTypeHasDoc (Rep a), HaveCommonTypeCtor b a) => TypeDocHaskellRep b #
Implement typeDocHaskellRep
on example of given concrete type.
This is a best effort attempt to implement typeDocHaskellRep
for polymorhpic
types, as soon as there is no simple way to preserve type variables when
automatically deriving Haskell representation of a type.
concreteTypeDocHaskellRepUnsafe :: (Typeable a, GenericIsoValue a, GTypeHasDoc (Rep a)) => TypeDocHaskellRep b #
Version of concreteTypeDocHaskellRep
which does not ensure
whether the type for which representation is built is any similar to
the original type which you implement a TypeHasDoc
instance for.
haskellRepNoFields :: TypeDocHaskellRep a -> TypeDocHaskellRep a #
Erase fields from Haskell datatype representation.
Use this when rendering fields names is undesired.
haskellRepStripFieldPrefix :: HasCallStack => TypeDocHaskellRep a -> TypeDocHaskellRep a #
Cut fields prefixes which we use according to the style guide.
E.g. cmMyField
field will be transformed to myField
.
homomorphicTypeDocMichelsonRep :: SingI (ToT a) => TypeDocMichelsonRep a #
Implement typeDocMichelsonRep
for homomorphic type.
concreteTypeDocMichelsonRep :: (Typeable a, SingI (ToT a), HaveCommonTypeCtor b a) => TypeDocMichelsonRep b #
Implement typeDocMichelsonRep
on example of given concrete type.
This function exists for the same reason as concreteTypeDocHaskellRep
.
concreteTypeDocMichelsonRepUnsafe :: (Typeable a, SingI (ToT a)) => TypeDocMichelsonRep b #
Version of concreteTypeDocHaskellRepUnsafe
which does not ensure
whether the type for which representation is built is any similar to
the original type which you implement a TypeHasDoc
instance for.
Orphan instances
Each ((Typeable :: [Type] -> Constraint) ': (ReifyList TypeHasDoc ': ([] :: [[Type] -> Constraint]))) (i ': (o ': ([] :: [[Type]]))) => TypeHasDoc (i :-> o) Source # | |
typeDocName :: Proxy (i :-> o) -> Text # typeDocMdDescription :: Markdown # typeDocMdReference :: Proxy (i :-> o) -> WithinParens -> Markdown # typeDocDependencies :: Proxy (i :-> o) -> [SomeTypeWithDoc] # typeDocHaskellRep :: TypeDocHaskellRep (i :-> o) # typeDocMichelsonRep :: TypeDocMichelsonRep (i :-> o) # |