| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Michelson.Typed.Haskell.Doc
Description
Documentation of types appearing in contracts.
Synopsis
- type ADTRep a = NonEmpty (ConstructorRep a)
- data ConstructorRep a = ConstructorRep {}
- crNameL :: forall a. Lens' (ConstructorRep a) Text
- crDescriptionL :: forall a. Lens' (ConstructorRep a) (Maybe Text)
- crFieldsL :: forall a a. Lens (ConstructorRep a) (ConstructorRep a) [FieldRep a] [FieldRep a]
- data FieldRep a = FieldRep {}
- frNameL :: forall a. Lens' (FieldRep a) (Maybe Text)
- frDescriptionL :: forall a. Lens' (FieldRep a) (Maybe Text)
- frTypeRepL :: forall a a. Lens (FieldRep a) (FieldRep a) a a
- newtype WithinParens = WithinParens Bool
- class (Typeable a, SingI (TypeDocFieldDescriptions a), FieldDescriptionsValid (TypeDocFieldDescriptions a) a) => TypeHasDoc a where
- type TypeDocFieldDescriptions a :: FieldDescriptions
- typeDocName :: Proxy a -> Text
- typeDocMdDescription :: Markdown
- typeDocMdReference :: Proxy a -> WithinParens -> Markdown
- typeDocDependencies :: Proxy a -> [SomeDocDefinitionItem]
- typeDocHaskellRep :: TypeDocHaskellRep a
- typeDocMichelsonRep :: TypeDocMichelsonRep a
- type TypeDocHaskellRep a = Proxy a -> FieldDescriptionsV -> Maybe (Maybe DocTypeRepLHS, ADTRep SomeTypeWithDoc)
- type TypeDocMichelsonRep a = Proxy a -> (Maybe DocTypeRepLHS, T)
- type FieldDescriptions = [(Symbol, (Maybe Symbol, [(Symbol, Symbol)]))]
- type PolyTypeHasDocC ts = Each '[TypeHasDoc] ts
- data SomeTypeWithDoc where
- SomeTypeWithDoc :: TypeHasDoc td => Proxy td -> SomeTypeWithDoc
- class HaveCommonTypeCtor a b
- class IsHomomorphic a
- genericTypeDocDependencies :: forall a. (Generic a, GTypeHasDoc (Rep a)) => Proxy a -> [SomeDocDefinitionItem]
- customTypeDocMdReference :: (Text, DType) -> [DType] -> WithinParens -> Markdown
- homomorphicTypeDocMdReference :: forall (t :: Type). (Typeable t, TypeHasDoc t, IsHomomorphic t) => Proxy t -> WithinParens -> Markdown
- poly1TypeDocMdReference :: forall t (r :: Type) (a :: Type). (r ~ t a, Typeable t, Each '[TypeHasDoc] [r, a], IsHomomorphic t) => Proxy r -> WithinParens -> Markdown
- poly2TypeDocMdReference :: forall t (r :: Type) (a :: Type) (b :: Type). (r ~ t a b, Typeable t, Each '[TypeHasDoc] [r, a, b], IsHomomorphic t) => Proxy r -> WithinParens -> Markdown
- homomorphicTypeDocHaskellRep :: forall a. (Generic a, GTypeHasDoc (Rep a)) => TypeDocHaskellRep a
- concreteTypeDocHaskellRep :: forall a b. (Typeable a, GenericIsoValue a, GTypeHasDoc (Rep a), HaveCommonTypeCtor b a) => TypeDocHaskellRep b
- concreteTypeDocHaskellRepUnsafe :: forall a b. (Typeable a, GenericIsoValue a, GTypeHasDoc (Rep a)) => TypeDocHaskellRep b
- haskellAddNewtypeField :: Text -> TypeDocHaskellRep a -> TypeDocHaskellRep a
- haskellRepNoFields :: TypeDocHaskellRep a -> TypeDocHaskellRep a
- haskellRepStripFieldPrefix :: HasCallStack => TypeDocHaskellRep a -> TypeDocHaskellRep a
- homomorphicTypeDocMichelsonRep :: forall a. SingI (ToT a) => TypeDocMichelsonRep a
- concreteTypeDocMichelsonRep :: forall a b. (Typeable a, SingI (ToT a), HaveCommonTypeCtor b a) => TypeDocMichelsonRep b
- concreteTypeDocMichelsonRepUnsafe :: forall a b. (Typeable a, SingI (ToT a)) => TypeDocMichelsonRep b
- data DType where
- DType :: TypeHasDoc a => Proxy a -> DType
- newtype DStorageType = DStorageType DType
- dStorage :: forall store. TypeHasDoc store => DStorageType
- class GTypeHasDoc (x :: Type -> Type)
- class GProductHasDoc (x :: Type -> Type)
- dTypeDep :: forall (t :: Type). TypeHasDoc t => SomeDocDefinitionItem
- dTypeDepP :: forall (t :: Type). TypeHasDoc t => Proxy t -> SomeDocDefinitionItem
- buildADTRep :: forall a. (WithinParens -> a -> Markdown) -> ADTRep a -> Markdown
- applyWithinParens :: WithinParens -> Markdown -> Markdown
Documentation
type ADTRep a = NonEmpty (ConstructorRep a) Source #
Stands for representation of some Haskell ADT corresponding to
Michelson value. Type parameter a is what you put in place of
each field of the datatype, e.g. information about field type.
This representation also includes descriptions of constructors and fields.
data ConstructorRep a Source #
Representation of a constructor with an optional description.
Constructors
| ConstructorRep | |
crDescriptionL :: forall a. Lens' (ConstructorRep a) (Maybe Text) Source #
crFieldsL :: forall a a. Lens (ConstructorRep a) (ConstructorRep a) [FieldRep a] [FieldRep a] Source #
Representation of a field with an optional description.
newtype WithinParens Source #
Whether given text should be rendered grouped in parentheses (if they make sense).
Constructors
| WithinParens Bool |
class (Typeable a, SingI (TypeDocFieldDescriptions a), FieldDescriptionsValid (TypeDocFieldDescriptions a) a) => TypeHasDoc a where Source #
Description for a Haskell type appearing in documentation.
Minimal complete definition
Associated Types
type TypeDocFieldDescriptions a :: FieldDescriptions Source #
Description of constructors and fields of a.
See FieldDescriptions documentation for an example of usage.
Descriptions will be checked at compile time to make sure that only existing constructors and fields are referenced.
For that check to work instance Generic a is required whenever TypeDocFieldDescriptions
is not empty.
For implementation of the check see FieldDescriptionsValid type family.
type TypeDocFieldDescriptions a = '[] Source #
Methods
typeDocName :: Proxy a -> Text Source #
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).
default typeDocName :: (Generic a, KnownSymbol (GenericTypeName a)) => Proxy a -> Text Source #
typeDocMdDescription :: Markdown Source #
Explanation of a type. Markdown formatting is allowed.
typeDocMdReference :: Proxy a -> WithinParens -> Markdown Source #
How reference to this type is rendered, in Markdown.
Examples:
[Integer](#type-integer),[Maybe](#type-Maybe) [()](#type-unit).
Consider using one of the following functions as default implementation; which one to use depends on number of type arguments in your type:
If none of them fits your purposes precisely, consider using
customTypeDocMdReference.
default typeDocMdReference :: (Typeable a, IsHomomorphic a) => Proxy a -> WithinParens -> Markdown Source #
typeDocDependencies :: Proxy a -> [SomeDocDefinitionItem] Source #
All types which this type directly contains.
Used in automatic types discovery.
default typeDocDependencies :: (Generic a, GTypeHasDoc (Rep a)) => Proxy a -> [SomeDocDefinitionItem] Source #
typeDocHaskellRep :: TypeDocHaskellRep a Source #
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.
default typeDocHaskellRep :: (Generic a, GTypeHasDoc (Rep a), IsHomomorphic a) => TypeDocHaskellRep a Source #
typeDocMichelsonRep :: TypeDocMichelsonRep a Source #
Final michelson representation of a type.
For homomorphic types use homomorphicTypeDocMichelsonRep implementation.
For polymorhpic types consider using concreteTypeDocMichelsonRep as implementation.
default typeDocMichelsonRep :: (SingI (ToT a), IsHomomorphic a) => TypeDocMichelsonRep a Source #
Instances
type TypeDocHaskellRep a = Proxy a -> FieldDescriptionsV -> Maybe (Maybe DocTypeRepLHS, ADTRep SomeTypeWithDoc) Source #
Signature of typeDocHaskellRep function.
A value of FieldDescriptionsV is provided by the library to make sure that
instances won't replace it with an unchecked value.
When value is Just, it contains types which this type is built from.
First element of provided pair may contain name a concrete type which has
the same type constructor as a (or just a for homomorphic types), and
the second element of the pair - its unfolding in Haskell.
For example, for some newtype MyNewtype = MyNewtype (Integer, Natural)
we would not specify the first element in the pair because MyNewtype is
already a concrete type, and second element would contain (Integer, Natural).
For polymorhpic types like newtype MyPolyNewtype a = MyPolyNewtype (Text, a),
we want to describe its representation on some example of a, because
working with type variables is too non-trivial; so the first element of
the pair may be e.g. "MyPolyNewType Integer", and the second one shows
that it unfolds to (Text, Integer).
When rendered, values of this type look like:
(Integer, Natural)- for homomorphic type.MyError Integer = (Text, Integer)- concrete sample for polymorhpic type.
type TypeDocMichelsonRep a = Proxy a -> (Maybe DocTypeRepLHS, T) Source #
Signature of typeDocMichelsonRep function.
As in TypeDocHaskellRep, set the first element of the pair to Nothing
for primitive types, otherwise it stands as some instantiation of a type,
and its Michelson representation is given in the second element of the pair.
Examples of rendered representation:
pair int nat- for homomorphic type.MyError Integer = pair string int- concrete sample for polymorhpic type.
type FieldDescriptions = [(Symbol, (Maybe Symbol, [(Symbol, Symbol)]))] Source #
Description of constructors and fields of some datatype.
This type is just two nested maps represented as associative lists. It is supposed to be interpreted like this:
[(Constructor name, (Maybe constructor description, [(Field name, Field description)]))]
Example with a concrete data type:
data Foo
= Foo
{ fFoo :: Int
}
| Bar
{ fBar :: Text
}
deriving (Generic)
type FooDescriptions =
'[ '( "Foo", '( 'Just "foo constructor",
, '[ '("fFoo", "some number")
])
)
, '( "Bar", '( 'Nothing,
, '[ '("fBar", "some string")
])
)
]type PolyTypeHasDocC ts = Each '[TypeHasDoc] ts Source #
Constraint, required when deriving TypeHasDoc for polymorphic type
with the least possible number of methods defined manually.
data SomeTypeWithDoc where Source #
Data hides some type implementing TypeHasDoc.
Constructors
| SomeTypeWithDoc :: TypeHasDoc td => Proxy td -> SomeTypeWithDoc |
class HaveCommonTypeCtor a b Source #
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) Source # | |
Defined in Michelson.Typed.Haskell.Doc | |
| HaveCommonTypeCtor ac bc => HaveCommonTypeCtor (ac a :: k2) (bc b :: k4) Source # | |
Defined in Michelson.Typed.Haskell.Doc | |
class IsHomomorphic a Source #
Require this type to be homomorphic.
Instances
| IsHomomorphic (a :: k) Source # | |
Defined in Michelson.Typed.Haskell.Doc | |
| (TypeError ('Text "Type is not homomorphic: " :<>: 'ShowType (a b)) :: Constraint) => IsHomomorphic (a b :: k2) Source # | |
Defined in Michelson.Typed.Haskell.Doc | |
genericTypeDocDependencies :: forall a. (Generic a, GTypeHasDoc (Rep a)) => Proxy a -> [SomeDocDefinitionItem] Source #
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 Source #
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 :: forall (t :: Type). (Typeable t, TypeHasDoc t, IsHomomorphic t) => Proxy t -> WithinParens -> Markdown Source #
Derive typeDocMdReference, for homomorphic types only.
poly1TypeDocMdReference :: forall t (r :: Type) (a :: Type). (r ~ t a, Typeable t, Each '[TypeHasDoc] [r, a], IsHomomorphic t) => Proxy r -> WithinParens -> Markdown Source #
Derive typeDocMdReference, for polymorphic type with one
type argument, like Maybe Integer.
poly2TypeDocMdReference :: forall t (r :: Type) (a :: Type) (b :: Type). (r ~ t a b, Typeable t, Each '[TypeHasDoc] [r, a, b], IsHomomorphic t) => Proxy r -> WithinParens -> Markdown Source #
Derive typeDocMdReference, for polymorphic type with two
type arguments, like Lambda Integer Natural.
homomorphicTypeDocHaskellRep :: forall a. (Generic a, GTypeHasDoc (Rep a)) => TypeDocHaskellRep a Source #
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 :: forall a b. (Typeable a, GenericIsoValue a, GTypeHasDoc (Rep a), HaveCommonTypeCtor b a) => TypeDocHaskellRep b Source #
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 :: forall a b. (Typeable a, GenericIsoValue a, GTypeHasDoc (Rep a)) => TypeDocHaskellRep b Source #
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.
haskellAddNewtypeField :: Text -> TypeDocHaskellRep a -> TypeDocHaskellRep a Source #
Add field name for newtype.
Since newtype field is automatically erased. Use this function
to add the desired field name.
haskellRepNoFields :: TypeDocHaskellRep a -> TypeDocHaskellRep a Source #
Erase fields from Haskell datatype representation.
Use this when rendering fields names is undesired.
haskellRepStripFieldPrefix :: HasCallStack => TypeDocHaskellRep a -> TypeDocHaskellRep a Source #
Cut fields prefixes which we use according to the style guide.
E.g. cmMyField field will be transformed to myField.
homomorphicTypeDocMichelsonRep :: forall a. SingI (ToT a) => TypeDocMichelsonRep a Source #
Implement typeDocMichelsonRep for homomorphic type.
concreteTypeDocMichelsonRep :: forall a b. (Typeable a, SingI (ToT a), HaveCommonTypeCtor b a) => TypeDocMichelsonRep b Source #
Implement typeDocMichelsonRep on example of given concrete type.
This function exists for the same reason as concreteTypeDocHaskellRep.
concreteTypeDocMichelsonRepUnsafe :: forall a b. (Typeable a, SingI (ToT a)) => TypeDocMichelsonRep b Source #
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.
Doc element with description of a type.
Constructors
| DType :: TypeHasDoc a => Proxy a -> DType |
Instances
| Eq DType Source # | |
| Ord DType Source # | |
| Show DType Source # | |
| DocItem DType Source # | |
Defined in Michelson.Typed.Haskell.Doc Associated Types type DocItemPlacement DType :: DocItemPlacementKind Source # type DocItemReferenced DType :: DocItemReferencedKind Source # Methods docItemPos :: Natural Source # docItemSectionName :: Maybe Text Source # docItemSectionDescription :: Maybe Markdown Source # docItemSectionNameStyle :: DocSectionNameStyle Source # docItemRef :: DType -> DocItemRef (DocItemPlacement DType) (DocItemReferenced DType) Source # docItemToMarkdown :: HeaderLevel -> DType -> Markdown Source # docItemToToc :: HeaderLevel -> DType -> Markdown Source # docItemDependencies :: DType -> [SomeDocDefinitionItem] Source # docItemsOrder :: [DType] -> [DType] Source # | |
| type DocItemPlacement DType Source # | |
Defined in Michelson.Typed.Haskell.Doc | |
| type DocItemReferenced DType Source # | |
Defined in Michelson.Typed.Haskell.Doc | |
newtype DStorageType Source #
Doc element with description of contract storage type.
Constructors
| DStorageType DType |
Instances
dStorage :: forall store. TypeHasDoc store => DStorageType Source #
Shortcut for DStorageType.
class GTypeHasDoc (x :: Type -> Type) Source #
Generic traversal for automatic deriving of some methods in TypeHasDoc.
Minimal complete definition
gTypeDocHaskellRep
Instances
| (TypeError ('Text "Cannot derive documentation for void-like type") :: Constraint) => GTypeHasDoc (V1 :: Type -> Type) Source # | |
Defined in Michelson.Typed.Haskell.Doc Methods gTypeDocHaskellRep :: FieldDescriptionsV -> ADTRep SomeTypeWithDoc | |
| (GTypeHasDoc x, GTypeHasDoc y) => GTypeHasDoc (x :+: y) Source # | |
Defined in Michelson.Typed.Haskell.Doc Methods gTypeDocHaskellRep :: FieldDescriptionsV -> ADTRep SomeTypeWithDoc | |
| GTypeHasDoc x => GTypeHasDoc (D1 ('MetaData _a _b _c 'True) x) Source # | |
Defined in Michelson.Typed.Haskell.Doc Methods gTypeDocHaskellRep :: FieldDescriptionsV -> ADTRep SomeTypeWithDoc | |
| GTypeHasDoc x => GTypeHasDoc (D1 ('MetaData _a _b _c 'False) x) Source # | |
Defined in Michelson.Typed.Haskell.Doc Methods gTypeDocHaskellRep :: FieldDescriptionsV -> ADTRep SomeTypeWithDoc | |
| (GProductHasDoc x, KnownSymbol ctor) => GTypeHasDoc (C1 ('MetaCons ctor _1 _2) x) Source # | |
Defined in Michelson.Typed.Haskell.Doc Methods gTypeDocHaskellRep :: FieldDescriptionsV -> ADTRep SomeTypeWithDoc | |
class GProductHasDoc (x :: Type -> Type) Source #
Product type traversal for TypeHasDoc.
Minimal complete definition
gProductDocHaskellRep
Instances
| GProductHasDoc (U1 :: Type -> Type) Source # | |
Defined in Michelson.Typed.Haskell.Doc Methods gProductDocHaskellRep :: [(Text, Text)] -> [FieldRep SomeTypeWithDoc] | |
| (GProductHasDoc x, GProductHasDoc y) => GProductHasDoc (x :*: y) Source # | |
Defined in Michelson.Typed.Haskell.Doc Methods gProductDocHaskellRep :: [(Text, Text)] -> [FieldRep SomeTypeWithDoc] | |
| TypeHasDoc a => GProductHasDoc (S1 ('MetaSel ('Nothing :: Maybe Symbol) _1 _2 _3) (Rec0 a)) Source # | |
Defined in Michelson.Typed.Haskell.Doc Methods gProductDocHaskellRep :: [(Text, Text)] -> [FieldRep SomeTypeWithDoc] | |
| (TypeHasDoc a, KnownSymbol field) => GProductHasDoc (S1 ('MetaSel ('Just field) _1 _2 _3) (Rec0 a)) Source # | |
Defined in Michelson.Typed.Haskell.Doc Methods gProductDocHaskellRep :: [(Text, Text)] -> [FieldRep SomeTypeWithDoc] | |
dTypeDep :: forall (t :: Type). TypeHasDoc t => SomeDocDefinitionItem Source #
Create a DType in form suitable for putting to typeDocDependencies.
dTypeDepP :: forall (t :: Type). TypeHasDoc t => Proxy t -> SomeDocDefinitionItem Source #
Proxy version of dTypeDep.
buildADTRep :: forall a. (WithinParens -> a -> Markdown) -> ADTRep a -> Markdown Source #
Show given ADTRep in a neat way.
applyWithinParens :: WithinParens -> Markdown -> Markdown Source #