Comment

Stable — Stable features are ones that have earned their place in the core prose language.

{* Still to add: the villagers, and the well they gather at. *}

universe ClockworkVillage {
  describe {
    A quiet village simulation where the focus is observation,
    relationships, and small moments.
  }
}

What it is

A note for whoever edits the file next. A comment opens with {* and closes with *}, and nothing between the two is part of the universe. It never reaches the manifest, so nothing that reads the universe ever sees it.

That is the difference from a describe. A describe says what something means, and everyone who reads the universe reads it. A comment says something about the file — what is unfinished, why a block sits where it does — and only the next person to open the file reads it. If a reader of the field guide should know it, it belongs in a describe.

A comment can run over as many lines as it needs. It does not nest: the first *} closes it, however many {* came before. Braces inside a comment do not count, so a whole declaration can be set aside by wrapping it in one, as long as nothing inside it contains *}.

The village has not changed at all. The comment will be gone from the next page, and taking it out changes nothing about ClockworkVillage. That is what a comment is for.

Where it can live

Anywhere between two words: at file scope, inside any block, between the targets of a relationships block, even in the middle of a path.

There is one kind. // and # do not start a comment in prose, and each is refused with a reminder of how to write one.

Inside a describe or a title, a comment is not a comment. Those blocks keep exactly what was written, so the comment is kept as text, and everyone who reads the describe reads it too. Its marks still have to pair up there: a lone {* or *} inside a describe is an error.

How names find it

Nothing. A comment is never read, so a name inside one points at nothing and is not checked.

That includes markers. sprig observe gathers receipts from the comments in your code, but it does not read .prose files, so a marker written in a prose comment is not a receipt.

How it breaks

• SP019 UnterminatedBlockCommentError — A block comment was opened and never closed.
• SP020 StrayBlockCommentEndError — A block comment closer appeared without an opener.
• SP029 UnexpectedCharacterError — A character that prose has no use for appeared outside a describe or a title.

Decided in

• ADR030 DescribeInEdgeBlocks — Describe in edge blocks. Proposed.