# Vote autodoc convention for Temper in Markdown

With regular Temper, `/**...*/` comments get turned into docstrings for the following declaration.

Note the Python translation below includes the text of `f`'s `/**...*/` comment as a docstring for `def f`.

$ temper repl
$ /** Autodoc comment for f */ let f(x: Int): Int { x + 1 }
interactive#0: void
$ translate(0, "py")
Translated py for interactive#0
  interactive-0000/
    interactive_0000/
      __init__.py: text/python
        import interactive_0000.chunk as _0
        from temper_core import await_safe_to_exit
        await_safe_to_exit()
      chunk.py: text/python
        from builtins import int
        def f(x: 'int') -> 'int':
          'Autodoc comment for f'
          return x + 1
      __init__.py.map: application/json
        { "version": 3, "file": "py/interactive-⋯": [], "names": [], "mappings": "A;A;A" }
      chunk.py.map: application/json
        { "version": 3, "file": "py/interactive-⋯,CAAA;AAAlB;AAAqB,SAAAA,CAAC,AAAD,EAAI" }
interactive#1: void

With Temper in markdown, we have no such association.

# function f

*f* returns the successor of its argument.
    let f(

*x* can be any integer but if it's the maximum representible, 
the output will underflow. 
      x: Int
    
    ): Int {
      x + 1
    }

This document collects possible approaches to identifying some suffix of the preceding markdown chunk to serve as the docstring for a declaration that lexically follows the end of a markdown chunk.

Please vote for and/or against any or all of the following.
Put a `+` or `-` with your initials after `Votes:`.

For example below, ABC is voting for and DEF is voting against.

Votes: +ABC -DEF

For the purposes of the rules below, a markdown "paragraph" starts either after a blank line or at the start of a chunk of markdown between code blocks.

## Repeat the name

Not part of the comment

*f* is a function that does a thing.

    let f(): Void { ... }

The rule: if a markdown paragraph starts with the declaration name, not as a prefix of another identifier, ignoring common formatting meta-characters, then it and following paragraphs until the declaration are autodoc comments.

The autodoc above would be

> *f* is a function that does a thing.

Votes: +T for italics where we also don't go past headings. (Non-subject-first languages can still say `*f*: ...`.)

Variation 1, initial letter case is ignored:

> `*F* is a function ...`

Variation 2, italics is *required* around the name to avoid collision with, for example, the definite English article "a".

> `*f* is a function ...` but not `f is a function`.

Variation 3, recognize <code>nym\`...\`</code> conventions.

> <tt>nym\`f\` is a function ...</tt>

Variation 4, require `[f]` syntax for the first term and work to translate `[...]` links to doc cross-references and to eliminate links to the same paragraphs.

> `[f] is a function ...` but not `f is a function ...` but the `[f]` appears as `f` in the doc comment content.

## Haskell doc convention `|` associates forward

Not part of the comment

|*f* is a function that does a thing.

    let f(): Void { ... }

The rule: if a markdown paragraph starts with a `|` which is the only one in that line (to distinguish from tables) then it and following paragraphs until the declaration are autodoc comments.

The `|` prefix is not autodoc comment content.

The autodoc above would be

> *f* is a function that does a thing.

Votes:

## Markdown thematic breaks

Not part of the comment

-------------------------------------

*f* is a function that does a thing.

    let f(): Void { ... }

[Commonmark](https://spec.commonmark.org/0.31.2/#thematic-breaks) notes:

> A line consisting of optionally up to three spaces of indentation, followed by a sequence of three or more matching `-`, `_`, or `*` characters, each followed optionally by any number of spaces or tabs, forms a **thematic break**.

The rule: if a markdown paragraph follows a thematic break then it and following paragraphs until the declaration are autodoc comments.

The thematic break is excluded from the autodoc comment content.

The autodoc above would be

> *f* is a function that does a thing.

Votes:

Variation 1, also treat HTML comments containing only `-` like `<!--->` as thematic breaks to allow starting an autodoc comment where a visible break would be visually distracting:

> ```md
> Not a part of the doc comment.
>
> <!--->
>
> *f* is a function ...
>
> let f ...
> ```

## Explicit markers

Some kind of markers indicate that a paragraph has documentation semantics.

@function Flobbles the flangestan. This paragraph describes 
the following function.

This paragraph should also be part of the documentation flow.

@param combobulatorCount should be coinverse to the unitary
metric of the wayneshaft

    let flobbler(combobulatorCount: Int): Void {
        flangestan.flobble(2 * combobulatorCount);
    }

There might be markdown extensions that make these a bit cleaner. And we can definitely look at syntax other than `@foo`.