authorgravatar for ian@ianjohnson.devIan Johnson <ian@ianjohnson.dev> 2023-12-28 21:00:32-05:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2024-01-21 19:28:52-08:00
logfdb4eb3056ee85709f8d1af6c11641481de5e653
treef9293255a38da668b7b710590b8c6fdfabb83bd0
parentac2930332104cf1d1f51edca922b502ef3bd3f89

langref: add information about doctests

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.

1 files changed, 14 insertions(+), 0 deletions(-)

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