Autodoc: Generate all paragraphs of function docstring

[mnemnion]

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.