From 03afbf93ed6fff191e641bc021c42631e9197ba9 Mon Sep 17 00:00:00 2001 From: Liigo Zhuang Date: Mon, 6 Jul 2015 14:55:06 +0800 Subject: [PATCH] book: introduce `//!` doc comment in comments section Closes #26801 --- src/doc/trpl/comments.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/doc/trpl/comments.md b/src/doc/trpl/comments.md index 7687d2a57da92..e7eb48dc42c52 100644 --- a/src/doc/trpl/comments.md +++ b/src/doc/trpl/comments.md @@ -38,6 +38,17 @@ fn add_one(x: i32) -> i32 { } ``` +There is another style of doc comment, `//!`, to comment containing items (e.g. +crates, modules or functions), instead of the items following it. Commonly used +inside crates root (lib.rs) or modules root (mod.rs): + +``` +//! # The Rust Standard Library +//! +//! The Rust Standard Library provides the essential runtime +//! functionality for building portable Rust software. +``` + When writing doc comments, providing some examples of usage is very, very helpful. You’ll notice we’ve used a new macro here: `assert_eq!`. This compares two values, and `panic!`s if they’re not equal to each other. It’s very helpful