Document top-level doc comments, per #2288.

1 files changed, 12 insertions, 0 deletions

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#}