Open mnemnion opened 4 months ago
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
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.
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.
Zig Version
0.12.0
Steps to Reproduce and Observed Behavior
Write a public function with a multi-paragraph docstring, like so
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.