Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document limitations on block doc comments #1602

Merged
merged 2 commits into from
Sep 17, 2024
Merged

Document limitations on block doc comments #1602

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8fae0fd
Document limitations on block doc comments
GKFX Sep 7, 2024
42d3c9f
Make note about markdown a note
ehuss Sep 17, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion src/comments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down