4.6 Creating Documentation Forms🔗ℹ

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_name 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_name and extract_metavariables functions, except that only the first list of spaces is passed back when extract_space returns a list of lists.

• extract_name: 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.

  To convert a name (potentially dotted) to one of these forms, use doc_meta.extract_name or doc_meta.extract_identifier_name.

• 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 an identifier or map (like a result from extract_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.

Converts a potentially dotted name to an identifier or map suitable as a result for a ~extract_name function for doc_meta.transformer.

Extraction functions for use with doc_meta.transformer that handle a form that starts with two names, where the second is the name to document (while the first name is the documentation form’s name).

Extraction functions for use with doc_meta.transformer that are like doc_meta.head_extract_name, etc., but also check that the second name is followed by a parenthesized sequence of groups as a term.

Extraction functions for use with doc_meta.transformer that handle a form that starts with a name (the documentation form’s name) followed by a quoted pattern, analogous to macro or expr.macro.

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

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