Doc comments

A declaration’s docs are the /// lines right before it, in Markdown. A module’s are the //! lines at the top of its file. Editors show them on hover, fb doc writes them as JSON, and the registry shows a package’s.

//! Prices for a small shop: see [Price].

Import std.core

/// The price of `count` items at `each`, with one free for every ten.
///
/// # Examples
///
/// ```
/// Expect(Price(10, 5) == 45)
/// ```
Public Function Price(count: Int, each: Int): Int
    Return (count - count / 10) * each
End Function

Where they go

• The /// lines right before a declaration, each on a line of its own, before its attributes, with no blank line between, are its doc comment.
• A top-level Function, Struct, Class, Interface, Attribute, Enum, Global, Const, or Alias has one, and so do the members of a Struct, Class, Interface, or Extend, the Functions of an Extern block, and an Enum’s members.
• The //! lines at the top of a file, before its first line of code, are its module’s.
• //// is an ordinary comment. A /// comment on no declaration documents nothing, and fb doc warns about it.

What’s in one

A doc comment is Markdown, written as Rust’s are:

• The summary is its first sentence, which lists show: up to the first ., !, or ? outside code that a space follows, or that ends the first paragraph.
• Sections start with headings: # Errors for what it throws, # Panics for how it can be misused, and # Examples.
• Parameters go in backticks, as `count`.
• Links go in brackets, like [Price], [Stack.Push], or [std.collections.stack], and name a declaration as code where the comment is would: its type’s members, then its module’s declarations, those of the modules it imports, and the built-ins. Backticks and () can go inside, as in [`Push()`]. fb doc warns about a link that names nothing.

A member without a doc that implements an Interface’s member, or overrides a base Class’s, has that one’s.

Examples are tests

The code blocks under # Examples, in a fence with no language or fb, are tests: fb test compiles and runs each, named after its declaration, as shop.prices.Price (example). So a doc’s examples can’t go stale.

• An example has Import std.core, Import std.test, and its declaration’s module without writing them, and writes any other Import at its top.
• A line that starts with # is compiled but not shown, for setup a reader doesn’t need.
• A fence of fb no_run is only compiled, for code that would wait on a network or a person.
• An example’s errors, failures, and stack traces name the doc comment’s lines.

fb doc’s JSON

{
  "format": 1,
  "package": "shop",
  "version": "0.3.0",
  "modules": [
    {
      "name": "shop.prices",
      "file": "prices.fb",
      "doc": { "summary": "...", "markdown": "...", "sections": [], "links": [], "examples": [] },
      "items": []
    }
  ]
}

• A module has its name, its file from the package’s folder, its doc, and its items. A module with no Public declarations and no doc is left out, and they’re sorted by name.
• An item is a declaration users see: kind (function, struct, class, interface, attribute, enum, alias, global, const, field, static field, method, static method, constructor, operator, property, enum member, or extend), name, path (as links name it, like shop.prices.Price), signature (its first line, as written), attributes, visibility, file and line, doc, and for a type, an Enum, or an Extend, its members. A member with an inherited doc has doc_from, the path it came from.
• A doc has its summary; its markdown, without examples’ hidden lines; its sections, each a heading and its markdown; its links, each the text written and the path it names, or builtin for a built-in; and its examples, each one’s code, the line of its fence, and whether it runs.