From 8fae0fdd7475870f724ba7a4c347009f9b5df930 Mon Sep 17 00:00:00 2001 From: George Bateman Date: Sat, 7 Sep 2024 21:38:28 +0100 Subject: [PATCH 1/2] Document limitations on block doc comments --- src/comments.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/comments.md b/src/comments.md index 795bf637c..9b4262a9e 100644 --- a/src/comments.md +++ b/src/comments.md @@ -45,7 +45,8 @@ Line doc comments beginning with exactly _three_ slashes (`///`), and block doc comments (`/** ... */`), both outer doc comments, are interpreted as a special syntax for [`doc` attributes]. That is, they are equivalent to writing `#[doc="..."]` around the body of the comment, i.e., `/// Foo` turns into -`#[doc="Foo"]` and `/** Bar */` turns into `#[doc="Bar"]`. +`#[doc="Foo"]` and `/** Bar */` turns into `#[doc="Bar"]`. They must therefore +appear before something that accepts an outer attribute. Line comments beginning with `//!` and block comments `/*! ... */` are doc comments that apply to the parent of the comment, rather than the item @@ -55,6 +56,12 @@ modules that occupy a source file. The character `U+000D` (CR) is not allowed in doc comments. +It is conventional for doc comments to contain Markdown, as expected by +`rustdoc`. However, the comment syntax does not respect any internal Markdown. +``/** `glob = "*/*.rs";` */`` terminates the comment at the first `*/`, and the +remaining code would cause a syntax error. This slightly limits the content of +block doc comments compared to line doc comments. + > **Note**: The sequence `U+000D` (CR) immediately followed by `U+000A` (LF) would have been previously transformed into a single `U+000A` (LF). ## Examples From 42d3c9fa90392efcda3aa7b27edd886c82ce26d2 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 17 Sep 2024 15:43:58 -0700 Subject: [PATCH 2/2] Make note about markdown a note --- src/comments.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/src/comments.md b/src/comments.md index 9b4262a9e..d395767e2 100644 --- a/src/comments.md +++ b/src/comments.md @@ -56,11 +56,11 @@ modules that occupy a source file. The character `U+000D` (CR) is not allowed in doc comments. -It is conventional for doc comments to contain Markdown, as expected by -`rustdoc`. However, the comment syntax does not respect any internal Markdown. -``/** `glob = "*/*.rs";` */`` terminates the comment at the first `*/`, and the -remaining code would cause a syntax error. This slightly limits the content of -block doc comments compared to line doc comments. +> **Note**: It is conventional for doc comments to contain Markdown, as expected by +> `rustdoc`. However, the comment syntax does not respect any internal Markdown. +> ``/** `glob = "*/*.rs";` */`` terminates the comment at the first `*/`, and the +> remaining code would cause a syntax error. This slightly limits the content of +> block doc comments compared to line doc comments. > **Note**: The sequence `U+000D` (CR) immediately followed by `U+000A` (LF) would have been previously transformed into a single `U+000A` (LF).