Documenting Blocks

The definition site is the single source of truth

Every Block definition carries its documentation at the definition site — is, documentation, and references are the single source of truth inside the BML file itself, not scattered across external documents.

is names the idea; documentation explains it

is is a required, ultra-short noun phrase naming what a Block semantically represents — not a purpose statement and not full technical detail, both of which belong in documentation instead.

documentation is always required and defaults to Markdown in English — longer prose should use headings, paragraphs, and lists, since human-friendly formatting is part of BlockML, not decoration.

references carries every cross-link

references is the single place every documentation cross-link lives — each with an explicit relationship note — so documentation prose should describe concepts rather than repeat links that references already carries.

Filling is, documentation, and references

A Block fills is with a short noun phrase, documentation with fuller Markdown prose, and references with one cross-link carrying its own relationship note.

<!-- is, documentation, and references, filled at the definition site -->
<acme:Widget xmlns="http://blockml.org/bml"
  xmlns:acme="com.acme.example"
  xmlns:core="org.blockml.bml.core">

  <baseType>
    core:Block
  </baseType>
  <is>
    A generic composable part
  </is>
  <documentation>
    Widget is the handbook's running example of a minimal domain Block. It carries
    no members of its own and exists purely to illustrate identity and structure.
  </documentation>
  <references>
    <see type="core:Block" relation="Extends">
      Root type every Widget instance ultimately specializes.
    </see>
  </references>
</acme:Widget>

Widget's is stays a short noun phrase, its documentation expands on that in Markdown prose, and the core:Block cross-link sits in references with its own relation, Extends, attached — precisely so the documentation prose above it can stay focused on describing the Block, not on repeating that same link inline.

What to carry into the next pages

After this page, readers should be able to fill a Block's is, documentation, and references fields correctly, closing out this handbook's concept pages before the BML authoring format itself is described directly.