Autodoc: Allow multi-paragraph summary doc comments with `---`

[mnemnion]

Edit: this is intended behavior, jump to this link for why this issue is still open (other than the aesthetically-pleasing number).

Zig Version

0.12.0

Steps to Reproduce and Observed Behavior

Write a public function with a multi-paragraph docstring, like so

/// Prefabulate a Turboencabulator
///
/// Assumes memory is mutable and logarithmic. 
/// 
/// Up to six hydrocoptic marzlevanes may be provided.
///
/// Caller owns returned memory.
pub fn turboEncabulate(...) etc { ... }

Then generate docs.

Result: only the line "Prefabulate a Turboencabulator" is included in the docs.

Expected Behavior

As with top-level doc comments, I expected all of the doc comment to be included in the generated documentation, separated into paragraphs, as they appear in the source file.

[Vexu]

Are you looking at the function in a namespace's documentation?

Compare https://ziglang.org/documentation/master/std/#std.math.pow to fn pow in https://ziglang.org/documentation/master/std/#std.math

[mnemnion]

I was, yes.

Given that this is intended behavior, the bug label should be removed.

However, as a feature, it would be nicer if the split between the summary and the extended help were under the author's control.

A lightweight way to do that would be this:

---

Which in Markdown is just ---, three or more hyphens.

[mnemnion]

This could be done without requiring everyone to rewrite their documentation, by following the original standard unless there's a "below the fold" line in the docstring.

So any existing doc comment (and any future doc comment where the first-paragraph-only behavior is wanted), would do what autodocs does now: use the first paragraph as a summary, and add the full documentation to the function's page.

But if an author wants the fold somewhere else, just add ---.

This strikes me as a simple addition to the doc comment system, consistent with Markdown, easy to document as part of #19866.

[gracen-writes-code]

I've noticed this issue occurs with type aliases, even when looking at them individually. Is this also intended behavior?

For example, for pub const Codepoint = u24; with a multi-paragraph doc comment (explaining why u24 instead of u21), Autodoc only displays the first paragraph.