16. Test: Showcase Authoring JSON

This chapter presents the current profile-specific Waterloo Authoring JSON showcases in their rendered docstring form. A showcase is an editable syntax reference: it demonstrates the sections and content blocks that an Authoring JSON document can use for one profile, including paragraphs, nested lists, tables, and profile-specific sections where applicable.

Generate a showcase with waterlint before authoring or revising a docstring, for example:

waterlint gen-showcase-authoring-json --profile function --out function-showcase.json

The generated JSON is a starting point for learning the format, not a template to copy verbatim. Replace its placeholder identifiers, descriptions, and normative statements with documentation appropriate for the actual object. Use validate-json to validate the edited Authoring JSON and render-docstring to produce the raw Waterloo docstring.

This page is intended as feedback for human readers. It makes the currently distributed showcases visible in the documentation, so their practical shape and coverage can be reviewed without first generating and rendering the JSON files locally.

16.1. Profile: module

r"""
Preamble:
    profile:
        module
    normative_sections:
        Definitions, Contract, Public_classes, Public_functions, Public_types,\
        Public_variables, Public_constants
    status:
        stable
    scope:
        public
Definitions:
    Example:
        A demonstration class used only by this Authoring JSON showcase.
Terminology:
    showcase:
        A deliberately small document that demonstrates a supported authoring structure.
Contract:
    general:
        |Must| demonstrate the module-level Authoring JSON structures.
Description:
    This paragraph is followed by a nested list and a table block.
    |
    * A list item may contain nested items.
    + Nested items preserve their authoring structure.
    * Inline roles such as |var|`item` and |type|`Example` remain ordinary text values.
    |
    |begin_table|
    |title|
    Supported blocks
    |columns|
    Block |tab| Purpose
    |rows|
    paragraph |tab| Narrative text.
    list |tab| Ordered free-form points.
    table |tab| Structured values.
    |end_table|
Public_classes:
    waterloo_authoring_showcase.Example
Class_overview:
    Example:
        A class overview accepts the same free-form blocks as Description.
Public_functions:
    waterloo_authoring_showcase.make_example
Function_overview:
    make_example:
        Create an |class|`Example` for demonstration purposes.
Public_types:
    Mode_t:
        A type alias whose values select the desired demonstration mode.
Public_variables:
    default_mode:
        The default |var_type|`default_mode: Mode_t`.
Public_constants:
    SHOWCASE_VERSION:
        The fixed showcase format version.
Notes:
    Editing:
        Replace the qualified identifiers and descriptions with information about the target
        module.
"""

16.2. Profile: class

r"""
Preamble:
    profile:
        class
    normative_sections:
        Definitions, Contract, Derived_from, Factory, Public_classes, Public_methods,\
        Public_types, Public_variables, Public_constants
    scope:
        public
Definitions:
    Example:
        A class used to demonstrate class-specific Authoring JSON sections.
Contract:
    general:
        |Must| represent one configurable demonstration object.
    constructor:
        |Must| accept one |var|`mode` value.
    traits:
        final
Description:
    Class descriptions can combine prose with structured tables.
    |
    |begin_table|
    |columns|
    Mode |tab| Effect
    |rows|
    simple |tab| Use the compact demonstration.
    full |tab| Enable every optional feature.
    |end_table|
Derived_from:
    waterloo_authoring_showcase.BaseExample
Factory:
    waterloo_authoring_showcase.Example.from_config:
        Create an Example from configuration values.
        |
        |begin_table|
        |columns|
        Key |tab| Meaning
        |rows|
        mode |tab| Selected demonstration mode.
        |end_table|
Public_classes:
    waterloo_authoring_showcase.Example.Nested
Class_overview:
    Nested:
        A nested supporting class.
Public_methods:
    waterloo_authoring_showcase.Example.describe
Method_overview:
    describe:
        Return a human-readable description.
Public_types:
    State_t:
        A type alias for Example state values.
Public_variables:
    mode:
        The active demonstration mode.
Public_constants:
    DEFAULT_MODE:
        The mode selected when configuration omits one.
Notes:
    Factory:
        Factory entries are class-specific and use qualified function identifiers as keys.
"""

16.3. Profile: function

r"""
Preamble:
    profile:
        function
    normative_sections:
        Definitions, Contract, Description, Parameters, Returns, Raises
    scope:
        public
Definitions:
    Level:
        One supported level of detail.
Terminology:
    verbose:
        A mode that includes explanatory detail in the returned text.
Contract:
    general:
        |Must| return a description for the requested level.
    requires:
        |Must| receive a supported |var|`level` value.
    ensures:
        |Must| return a non-empty |type|`str`.
Description:
    |Must| use the following structured data to explain the level.
    |
    * The normal mode returns a concise description.
    * Verbose mode adds details.
    + Nested list entries remain available in Authoring JSON.
    |
    |begin_table|
    |title|
    Behavior of |var|`level`
    |columns|
    Level |tab| Result
    |rows|
    basic |tab| Concise text.
    detailed |tab| Expanded text.
    |end_table|
Parameters:
    level:
        The requested level.
        |
        |begin_table|
        |columns|
        Value |tab| Meaning
        |rows|
        basic |tab| Select concise output.
        detailed |tab| Select expanded output.
        |end_table|
    verbose:
        Whether the returned description includes additional detail.
Returns:
    A description matching |var|`level`.
    |
    |begin_table|
    |columns|
    Condition |tab| Returned content
    |rows|
    |var|`verbose` is |False| |tab| Concise description.
    |var|`verbose` is |True| |tab| Expanded description.
    |end_table|
Raises:
    ValueError:
        Raised if |var|`level` is unsupported.
        |
        |begin_table|
        |columns|
        Input |tab| Reason
        |rows|
        unknown |tab| No matching level exists.
        |end_table|
Notes:
    Workflow:
        Edit this document, validate it, and render it as a raw Waterloo docstring.
"""

16.4. Profile: method

r"""
Preamble:
    profile:
        method
    normative_sections:
        Definitions, Contract, Parameters, Returns, Raises
    scope:
        public
Definitions:
    Detail:
        The amount of information included in a description.
Contract:
    general:
        |Must| return a description of this instance.
    ensures:
        |Must| not modify the instance state.
Description:
    Methods use the same text-block structures as functions.
    |
    |begin_table|
    |columns|
    detail |tab| Result
    |rows|
    false |tab| A concise description.
    true |tab| An expanded description.
    |end_table|
Parameters:
    detail:
        Whether to include additional details.
Returns:
    A |type|`str` describing this instance.
Raises:
Notes:
    Receiver:
        The receiver parameter is represented by the method profile and normally needs no
        Parameters entry.
"""

16.5. Profile: inherited_method

r"""
Preamble:
    profile:
        inherited_method
    normative_sections:
        Definitions, Contract
    scope:
        public
Definitions:
    InheritedBehavior:
        Behavior supplied by a base-class method.
Contract:
    general:
        |Must| retain the behavior of the referenced base method.
    base:
        waterloo_authoring_showcase.Base.describe
Description:
    An inherited-method document records its base implementation explicitly.
    |
    |begin_table|
    |columns|
    Source |tab| Behavior
    |rows|
    Base.describe |tab| Inherited without local changes.
    |end_table|
Notes:
    Override:
        Use a method profile rather than inherited_method when the subclass changes the
        contract.
"""