From bc900cdeaf3434acc150a8db203eb5a485c09b67 Mon Sep 17 00:00:00 2001
From: Nathan Michaels <nathan@nmichaels.org>
Date: Sun, 5 Jul 2020 18:39:28 -0400
Subject: [PATCH] Document top-level doc comments, per #2288.

---
 doc/langref.html.in | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 6fb6557ca6..f4320df1b5 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -392,6 +392,18 @@ const Timestamp = struct {
       in the middle of an expression, or just before a non-doc comment.
       </p>
       {#header_close#}
+      {#header_open|Top-Level Doc Comments#}
+      <p>User documentation that doesn't belong to whatever
+      immediately follows it, like package-level documentation, goes
+      in top-level doc comments. A top-level doc comment is one that
+      begins with two slashes and an exclamation point:
+      {#syntax#}//!{#endsyntax#}.</p>
+      {#code_begin|syntax|tldoc_comments#}
+//! This module provides functions for retrieving the current date and
+//! time with varying degrees of precision and accuracy. It does not
+//! depend on libc, but will use functions from it if available.
+      {#code_end#}
+      {#header_close#}
       {#header_close#}
       {#header_open|Values#}
       {#code_begin|exe|values#}