013_metadata

Metadata

Overview

The CVM provides facility for attaching a metadata map to a defined symbol. The purpose of metadata is to provide any information on a defined symbol regardless of the concrete value this symbol holds.

Some metadata information, if specified, MUST follow a particular structure for external purposes. For instance, this CAD describes how to document a symbol by following an expected structure.

Other information CAN follow any arbitrary structure.

Usage

Declaring metadata

Metadata is a map containing any arbitrary set of key-values. It is specified after the defined symbol, prefixed with ^:

(def some-symbol

  ^{:my ["meta" :data]}

  42)

Retrieving metadata

The core library defines a function for retrieving metadata:

(lookup-meta 'some-symbol)

;; Following previous example, returns `{:my ["meta" :data]}`

Each account stores a map of symbol to metadata map under :metadata:

(get (account *address*)
     :metadata)

;; Following previous examples, returns `{'some-symbol {:my ["meta" :data]}}`

Standard structures

For some purposes, metadata must follow at least a set of contraints so that the CVM or any external consumer has access to relevant information.

Documentation

Attaching documentation to a symbol allows any user to gain insight about the purpose of that symbol. Notably, it can provide information regarding how a function is intended to be used and why.

User MAY specify any information as described below. None is mandatory. When specified, structure MUST conform as expected by any external consumer.

A documentation map MAY be attached to metadata under :doc.

Reference example:

(defn add

  ^{:doc {:description "Adds 2 numbers together."
          :errors      {:CAST "If an argument cannot be cast to a number"}
          :examples    [{:code "(add 2 3)"}]
          :signature   [{:params  [a b]
                         :returns Number}]
          :type        :function}}

  :implementation...)

Documentation map MAY contain any of the key-values described in the following subsections.

:description

String describing the symbol in human language .

TODO. Also a vector of strings where each string is a paragraph for easier formatting?

:errors

Assuming the symbol is callable, map of error code to string describing in human language how and why calling this function might fail.

See also CAD 011 about errors.

:examples

Assuming the symbol is callable, vector of examples where an example is a map which MAY contain:

Key	Value
:code	String, excerpt of code demonstrating a function call

TODO. Should it be a string? Is it for memory issues? TODO. Should it also have a :return key-value?

:signature

Assuming the symbol is callable, vector of signatures where a signature is a map which MAY contain:

Key	Value
:params	Vector of parameters
:returns	Type of returned value

TODO. Is there a list of supported types for :returns? More future-proof to have a human-readable string?

:type

Keyword designating what category the symbol belongs to:

Keyword	Meaning
:function	Symbol is a regular function
:macro	Symbol is a macro

TODO. What about other values?

Expanders

As described in CAD 009, expanders MUST have at least {:expander true} in their metadata.

TODO. Use :expander? for consistency.

TODO. Example here? Or rather in CAD009?

TODO. Other sections besides documentation and expanders?