On this page:
doc
doc_  meta.space
doc.bridge
doc_  meta.transformer
head_  extract_  name
parens_  extract_  name
operator_  macro_  extract_  name
identifier_  macro_  extract_  name
head_  extract_  metavariables
parens_  extract_  metavariables
operator_  macro_  extract_  metavariables
identifier_  macro_  extract_  metavariables
head_  extract_  typeset
parens_  extract_  typeset
operator_  macro_  extract_  typeset
identifier_  macro_  extract_  typeset
doc_  meta.add_  metavariable
doc_  meta.typeset_  rhombusblock
8.17.0.6

3.6 Creating Documentation Forms🔗ℹ

 import: scribble/doc_meta package: rhombus-scribble-lib

A space for documentation forms.

definition

doc.bridge name:

  body

  ...

Binds name as a documentation form in the doc space for use with the doc documentation form. The bodys should produce a value created by doc_meta.transformer.

function

fun doc_meta.transformer(

  ~extract_desc: extract_desc :: Function.of_arity(1),

  ~extract_space: extract_space :: Function.of_arity(1),

  ~extract_defined: extract_defined :: Function.of_arity(2),

  ~extract_metavariables: extract_metavariables :: Function.of_arity(3),

  ~extract_typeset: extract_typeset :: Function.of_arity(3),

  ~extract_sort_order: extract_sort_order :: Function.of_arity(2):

                         fun (_, [spc, ...]): [100 || spc, ...],

  ~extract_spacer_infos: extract_spacer_infos :: Function.of_arity(2):

                           fun (_, [spc, ...]): [{} || spc, ...]

)

Combines a set of functions into a value suitable for use with doc.bridge:

  • extract_desc: Takes a syntax object and returns a string or list of strings describing the documented binding or bindings. A description string is shown in the definition box, such as "function" for function documentation.

    If a list of strings is returned, the extract_space and extract_defined functions should produce a list with the same number of values for the given syntax object. The extract_metavariables will receive a list of space lists, and it will also receive a list of converter functions.

  • extract_space: Takes a syntax object and returns a space, a list of spaces, or a lists of space lists; the result must be a list of space lists if extract_desc returned a list. Each space is a keyword for a built-in space (see rhombus), a symbol, or #false. A space list indicates a list of spaces where the identifier is bound (e.g., the class binds in the ~class and ~annot spaces).

    As a convenience, the result is is passed back to the extract_defined and extract_metavariables functions, except that only the first list of spaces is passed back when extract_space returns a list of lists.

  • extract_defined: Takes a syntax object and a space or space list (produced by extract_space) and returns a defined name or list of defined names. A defined name is either

    • an identifier that is defined (which is equivalent to a map from #'target to the identifier);

    • a map where the following keys are recognized:

      • #'target (required): An identifier that is defined. More precisely, this identifier’s binding in the label meta phase is the defined binding.

      • #'root: An identifier that corresponds to a namespace, where the #'target is defined within the namespace. If this key is not present or it is mapped to #false, then no namespace prefix is shown.

      • #'raw: A string to use for showing the defined name. If this key is not present, the raw text of the #'target identifier is used.

      • #'raw_prefix: A string that should prefix the defined name, but it is not part of the defined name for searching, and the prefix is rendered in a way to indicate that it’s providing context instead of naming a module export. This prefix is intended to be a module prefix for exports that are meant to be used in dotted form, instead of through an opened module import.

  • extract_metavariables: Takes a syntax object, a space or space list (produced by extract_space), and a set of names to be typeset as metavariables. The result must be a new set of metavariables. Add to the set using doc_meta.add_metavariable.

  • extract_typeset: Takes a syntax object, a space, space list, or list of space lists (produced by extract_space), and a function or list of converter functions. Each converter function converts a syntax object at the location of the defined name and produces a syntax object for the typeset replacement. The result should be a syntax object to use as an expression that produces the typeset form, typically produced via doc_meta.typeset_rhombusblock.

    Each convert function accepts optional arguments:

    • ~as_wrap: a true value (the default) indicates that the result should include an escape, so it’s suitable for splicing into a rhombusblock form.

    • ~as_redef: a true value (not the default) indicates that the result should should not be a hyperlink target, because it’s a secondary definition of the binding.

    • ~as_meta: a true value (not the default) indicates that the result should be typeset as a metavariable (usually italic) instead of a variable.

  • extract_sort_order: Takes a syntax object and a list of space lists (the normalized result of extra_space) and returns a list of exact integers used to order documentation searches for the corresponding definition relative to other documentation entries.

  • extract_spacer_infos: Takes a syntax object and list of space lists (the normalized result of extra_space) and returns a list of maps. Each map provides additional information for a documented binding that is stored in the cross-reference database — especially for use by rhombusblock and similar in cooperation with spacers. Each key should be mapped to a serializable value or identifier, and identifier values are converted to a serializable form that retains only binding information. See Spacers and Indirect Binding for information about recognized keys.

function

fun head_extract_name(

  stx :: Syntax, space :: SpaceName

) :: Identifier || List

 

function

fun parens_extract_name(

  stx :: Syntax, space :: SpaceName

) :: Identifier || List

 

function

fun operator_macro_extract_name(

  stx :: Syntax, space :: SpaceName

) :: Identifier || List

 

function

fun identifier_macro_extract_name(

  stx :: Syntax, space :: SpaceName

) :: Identifier || List

 

function

fun head_extract_metavariables(

  stx :: Syntax, space :: SpaceName, vars :: Map

) :: Map

 

function

fun parens_extract_metavariables(

  stx :: Syntax, space :: SpaceName, vars :: Map

) :: Map

 

function

fun operator_macro_extract_metavariables(

  stx :: Syntax, space :: SpaceName, vars :: Map

) :: Map

 

function

fun identifier_macro_extract_metavariables(

  stx :: Syntax, space :: SpaceName, vars :: Map

) :: Map

 

function

fun head_extract_typeset(

  stx :: Syntax, space :: SpaceName, subst

) :: Syntax

 

function

fun parens_extract_typeset(

  stx :: Syntax, space :: SpaceName, subst

) :: Syntax

 

function

fun operator_macro_extract_typeset(

  stx :: Syntax, space :: SpaceName, subst

) :: Syntax

 

function

fun identifier_macro_extract_typeset(

  stx :: Syntax, space :: SpaceName, subst

) :: Syntax

Extraction functions for use with doc_meta.transformer that handle common documentation patterns.

function

fun doc_meta.add_metavariable(

  vars :: Map,

  id :: Identifier,

  ~is_nonterminal = #false

) :: Map

For use by the ~extract_metavariables component of a doc_meta.transformer construction.

function

fun doc_meta.typeset_rhombusblock(

  form :: Syntax,

  ~at: at_form :: Syntax = form,

  ~is_pattern = #false,

  ~options: options :: Term = '(~inset: #false)'

) :: Syntax

For use by the ~extract_typeset component of a doc_meta.transformer construction.