3.2 Documenting Bindings🔗ℹ

If the ~lang option is specified, then the module is documented as a language module for use with #lang.

If the ~no_declare option is specified, then the module declaration is rendered in the document, but it does not set context for doc forms.

The ~use_sources option declares modules that should be treated as exporting modules for hyperlinking purposes, even though the rendered documentation says that the bindings originate from the main mod_path. Use ~use_sources when bindings are reexported from multiple documented modules, and where bindings accessed via all of those modules should be linked to the docs in this section.

The docmodule form must be used only once without ~no_declare within a section, but a section’s docmodule can be shadowed by a declaration in a subsection.

Each entry clause is typical a doc entry form. For example, use the fun doc entry form to document a function. An entry can also be ~include to extract documentation attached to a definition (e.g., extracted from a fun or enum definition that includes ~doc). New doc entry forms can be defined with doc.bridge. All of the documented forms are shown together as one documentation box in the rendered document.

Each pre-defined doc entry form has the same name and basic shape as a Rhombus definition form. For example, the fun doc entry form can be used to document functions that are implemented using fun. A doc entry form may not have exactly the same syntax as the definition form, however. For example, the fun doc entry form supports only a single function case, and multiple cases are meant to be documented with multiple uses of the fun doc entry form. A doc entry form typically also does not require the body part of the corresponding definition form, but it will typically allow the body to be written and typeset that body literally. The set of doc entry forms listed in entry is merely representative, because new forms can be added (and not even all of the predefined ones are listed there).

The list of descriptions to describe the documented bindings is usually written inside {} using @ notation. For example, the following use of doc defines Widget, ok_button, and make_panel all together:

@doc(

annot.macro 'Widget'

def ok_button :: Widget

fun make_panel(label :: String,

[child :: Widget, ...]) :: Widget

){

A @rhombus(Widget, ~annot) is an interactive thing, and the

constant @rhombus(ok_button) is a stock widget. Use @rhombus(make_panel)

to combine several widgets into a titled panel, where @rhombus(label)

provide the panel's title.

}

Doc entry forms like fun and annot.macro are responsible for extracting the relevant name that is being documented via doc. They also extract names that should be treated as metavariables in the documentation, such as the argument label to make_panel, so that when @rhombus(label) is used in the description, it renders as a metavariable there.

Each entry is otherwise typeset as in rhombusblock content, which means that #, can be used to escape from literal typesetting and write an expression that produces a Scribble element. to replace the #,(expr) escape.

Before doc entry forms, a prep declaration can bind identifiers to customize their treatment in typesetting:

• A ~nonterminal declaration causes the associated id as a nonterminal to refer to a nonterminal declared with grammar in another binding’s documentation. The op_or_id_name is the other binding, and nonterm_op_or_id_name is the name defined there, which defaults to id if not supplied. A builtin_space specification indicates the binding’s space, and it’s needed if the binding space of op_or_id_name is distinct from the expression binding space.

• A ~nonterminal_key declaration selects the way that nonterminals defined in this doc form can be referenced by other doc forms. By default, the first binding defined among the entrys is used, but ~nonterminal_key can select among others.

• A ~literal form specified ids that are to be terated as literals (no metavariables) in entrys. This form is normally not needed, since identifiers used without a $ in entrys are generally treated as literal.

• A ~meta form indicates that the documented bindings are provided meta, while ~also_meta indicates that the documented bindings are provided both normally and meta. At most one of ~meta and ~also_meta can be used.

Because nonterminal names tend to be short and easily confused with other uses, however, nonterminal names bound with nonterminal are not recognized by rhombus. Instead, nontermref must be used to explicitly refer to the nonterminal (with a link to its definition).

Each arg is parsed like a fun argument to infer argument bindings as metavariables. Referencing a metavariable in the description body of doc with rhombus typesets the name in the same way as the argument variable. Similarly, each arg_term is parsed as for an operator argument.

To document a function or operator with multiple cases, uses fun or operator multiple times with the same id_name or op_or_id_name in the same doc form.

In the quoted_terms, a use of $ indicates that the subsequent identifier is a metavariable, as opposed to a literal. The $ itself will not be rendered, but the identifier will be rendered as a metavariable. Furthermore, it may refer to a nonterminal that is defined using grammar or bound with a ~nonterminal preparation in the enclosing doc form.

In the annot.macro case, maybe_fallback can provide an alternate annotation name that is used when hyperlinking method names in rhombus and rhombusblock forms. When the context of a method name indicates the documented op_or_id_name but the method cannot be found within that name as a namespace, then the id after ~method_fallback is tried as a namespace. Typically, id implies op_or_id_name, but not necessarily; for example, ReadableString falls back to String due to the way that String method accept ReadableStrings.

The following example demonstrates documenting a widget expression macro with a metavariable direction that is specified via grammar. Meanwhile, ~nonterminal is used to make widget_expr hyperlink to the expr nonterminal that is defined in the Rhombus manual.

@doc(

~nonterminal:

widget_expr: block expr

expr.macro 'widget:

~label: $expr

$direction

$widget_expr

...'

grammar direction:

~horiz

~vert

){

Creates a widget, where each @rhombus(widget_expr) supplies a

child widget for the combined widget.

}

Note that methods and properties are defined standalone, as opposed to being inside class or interface. That’s why a in_id_name is needed to identify the enclosing class or interface. The id before in_id_name is treated as a metavariable.

The operator_order form does not document a binding itself, but is meant to be used alongside expr.macro and similar when documenting a prefix or infix operator. Each option is typically ~order: name to document the operator’s order or a ~stronger_than or ~weaker_than form to document its precedence directly.