This chapter is from the book
This chapter is from the book
This chapter is from the book
Comments
So far, the source code in this chapter has not contained comments. Comments appear in source code for a variety of reasons, including identifying the author, highlighting license information, documenting functions, explaining complex algorithms, or simply providing important context.
Rust supports C-style comments. The // characters start a comment until the end of the line. You can frame multiline comments within the /* and */ characters.
In Listing 2.8, comments are added to the “Hello, World” source code to identify the author, source file, and the purpose of the application. Both multiline and single-line comments are shown.
Code Listing 2.8. “Hello, World” program with comments
/* Author: Donis Marshall
Hello.rs
Hello, World program
*/
// Displays hello, world message
fn main(){
println!("Hello, world!");
}
Rust also supports documentation comments. Documentation comments are compiled into an HTML page using the rustdoc tool. This tool is automatically included in the Rust toolchain. Compiling the documentation comments creates several HTML files in the {package}/target/doc/{package} directory. The main HTML file is index.html and can be opened in any browser.
For documentation, there are single-line comments and multiline comments—both support markdown. Single-line documentation comments use the /// characters. Multiline documentation comments are enclosed within the /** and **/ characters. Documentation comments apply to the next entity in the source file, such as a struct or function.
Let’s look at another version of the “Hello, World” application—as a library crate. This library exposes a hello_world function that returns a greeting in various languages. The function accepts a parameter that selects a specific language, using the major-minor language code, for displaying “Hello, world!” Listing 2.9 shows the function with documentation comments.
Code Listing 2.9. Multilingual “Hello, World” program with comments
/** Display hello based on the
language (major.MINOR) provided.
Languages support: enUS, enUK,
frFR, and hiIN.
**/
pub fn hello_world(language:&str)->&'static str {
match language {
"enUS"=>"Hello, world!",
"enUK"=>"Good day, world!",
"frFR"=>"Bonjour le monde!",
"hiIN"=>"नमस्ते दुनिया!",
_=>"Hello, world!"
}
}
The //! characters precede documentation comments that apply to the parent entity, instead of the next. This is most often the current crate. Here is documentation for the hello library crate with markup included:
The markup highlights the first line in bold:
//! <b>Hello library crate</b>
The paragraph tags insert linefeeds:
//! <p>Author: Donis Marshall //! <p>Apache 2.0 License
You can also add sample code to your documentation comments. This can provide invaluable guidance to users of the application. The sample code within documentation code can also be executed as unit tests. Place the sample code in the Examples section. Sections are designated with the /// # characters. Notice there is a space between /// and #. Bracket the code snippet with three backticks (///```) before and after. Listing 2.10 shows the sample code.
Code Listing 2.10. Sample code within documentation comments
/// # Examples
///
/// ```
/// let greeting=hello::hello_world("hiIN");
/// ```assert_eq!(greeting, "नमस्ते दुनिया!");
/// ```
///
The cargo test command will execute both normal and documentation unit tests. In addition, the following command compiles documentation comments using the rustdoc tool, generating the index.html file and other related files:
cargo doc
Figure 2.1 shows the index.html file in the browser from compiling the previously shown documentation comments.
)
Figure 2.1 Index.html file result from compiling documentation comments
Figure 2.2 shows the documentation comments for the hello_world function.
)
Figure 2.2 Documentation comments for the hello_world function