From fdb4eb3056ee85709f8d1af6c11641481de5e653 Mon Sep 17 00:00:00 2001
From: Ian Johnson <ian@ianjohnson.dev>
Date: Thu, 28 Dec 2023 21:00:32 -0500
Subject: [PATCH] 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.
---
 doc/langref.html.in | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 0dbf427e7d..d5bbb20f7a 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -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>