Documentation

Given a list of FieldDefs, this associates each FieldDef with the additional documentation comment provided in the StrMap (SomeField rec) Text for that entity, if any is present.

Precondition: The [FieldDef] comes from the PersistEntity rec that this is called for. Doing eg:

alignFields
  (entityFields (entityDef (Proxy :: Proxy User)))
  (strMap :: StrMap (SomeField Order) Text)

will be extremely weird.

Since: 0.1.0.0

Formats the SomeField rec in the keys of the Map to be formatted in the same way as the HaskellName present in a FieldDef.

Since: 0.1.0.0

A type for defining documentation for a schema.

Since: 0.1.0.0

The SchemaDocs maps a TypeRep of the Entity rec that is documented to the SomeDocs for that entity.

Since: 0.1.0.0

A wrapper around EntityDocs that allows them to be stored in a list together. Contains the RC constraint alias, which will ensure that all necessary constraints for document rendering are packaged in.

Expand this constraint synonym to pack necessary constraints in with the EntityDocs type. Used in a few places to ensure that constraints are easy to modify in one place.

Since: 0.1.0.0

EntityDocs contain the documentation comment for the Entity rec that is being documented, as well as a map of documentation for the fields of that entity.

Since: 0.1.0.0

An expression of EntityDoc is used to document the persistent schema. To construct an EntityDoc, you'll use the Entity constructor and the (--^) operator. Everything to the right of the (--^) operator is a 'FieldDoc rec' for the given entity.

This type is a monad, and you can use do notation to sequence the documentation.

doc :: EntityDoc
doc =  do
  User --^ "Documentation for a User"
  Dog --^ "Documentation for a Dog"

Since: 0.1.0.0

A FieldDoc expression provides documentation for the given Entity. This type is a Monad and you will want to use do notation to create this.

There are two ways to create FieldDoc lines:

• String literals. These are collected and appended as documentation for the entity itself.
• The (#) operator, which accepts an EntityField and the text documentation for that entity.

Since: 0.1.0.0

Wrap the result type of a EntityField value so it can be stored in homogenous containers.

Since: 0.1.0.0

Expand this constraint synonym to pack necessary constraints for packing EntityField values into SomeFields.

A monad for writing documentation on an entity's fields. Collects the documentation into a Writer.

Since: 0.1.0.0

Define documentation for an entity. The left-hand side takes the Entity constructor, and the right hand side takes a FieldDoc expression that documents the entity and it's fields.

Example

x :: EntityDoc
x = do
  User --^ do
    "This comment is for the entity User."
    UserName # "This comment is for a field.""

Since: 0.1.0.0

Write documentation for the given EntityField.

Example

x :: EntityDoc
x = do
  User --^ do
    "This comment is for the entity User."
    UserName # "This comment is for a field.""

Since: 0.1.0.0