mirror/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2026-02-15 13:58:27 +00:00
Code Issues Packages Projects Releases Wiki Activity

langref: add information about doctests

Browse Source 
This creates a section in the language reference about doctests, which
is currently referenced by Autodoc in a tooltip when displaying a
doctest.

Some advice relevant to writing doctests is included, based on the
discussion on #16472.
This commit is contained in:
Ian Johnson 2023-12-28 21:00:32 -05:00 committed by Andrew Kelley
parent ac29303321
commit fdb4eb3056
1 changed files with 14 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
doc/langref.html.in
View File

@ -1106,6 +1106,7 @@ test "expect addOne adds one to 41" {
test addOne {
// A test name can also be written using an identifier.
// This is a doctest, and serves as documentation for `addOne`.
try std.testing.expect(addOne(41) == 42);
}
@ -1170,6 +1171,19 @@ fn addOne(number: i32) i32 {
be written before or after the code under test.
</p>
{#see_also|The Global Error Set|Grammar#}
{#header_open|Doctests#}
<p>
Test declarations named using an identifier are <em>doctests</em>. The identifier must refer to another declaration in
scope. A doctest, like a {#link|doc comment|Doc Comments#}, serves as documentation for the associated declaration, and
will appear in the generated documentation for the declaration.
</p>
<p>
An effective doctest should be self-contained and focused on the declaration being tested, answering questions a new
user might have about its interface or intended usage, while avoiding unnecessary or confusing details. A doctest is not
a substitute for a doc comment, but rather a supplement and companion providing a testable, code-driven example, verified
by <kbd>zig test</kbd>.
</p>
{#header_close#}
{#header_close#}
{#header_open|Test Failure#}
<p>