Rust comments: Difference between revisions
From wikinotes
Line 23: | Line 23: | ||
= Doc Comments = | = Doc Comments = | ||
<blockquote> | <blockquote> | ||
doc-comments are written in [[markdown]]. | == Generate/View Docs == | ||
<blockquote> | |||
<syntaxhighlight lang="bash"> | |||
cargo doc --open # build, and view docs (current project, and it's dependencies) | |||
</syntaxhighlight> | |||
</blockquote><!-- Document --> | |||
== Basics == | |||
<blockquote> | |||
doc-comments are written in [[markdown]], and code-blocks default to rust as the language.<br> | |||
assertions written in doc-comments are run with your test-suite. | |||
<syntaxhighlight lang="rust"> | <syntaxhighlight lang="rust"> | ||
/// doc-comment for following item ( | //! # My Module (doc-comment for enclosing item) | ||
fn | //! | ||
//! This module does foo, and bar, and baz. | |||
//! (can be used for functions, but not idiomatic) | |||
//! (often used for crates) | |||
/// Feeds the cat (doc-comment for following-item) | |||
/// | |||
/// # Examples | |||
/// | |||
/// ``` | |||
/// let name = "mycat"; | |||
/// let success = feed(name); | |||
/// assert!(success); | |||
/// ``` | |||
fn feed_cat(name: &str) -> bool { | |||
println!("hi") | println!("hi") | ||
} | } | ||
</syntaxhighlight> | |||
<syntaxhighlight lang="rust"> | |||
</syntaxhighlight> | |||
</blockquote><!-- Basics --> | |||
== Common Headers == | |||
<blockquote> | |||
It's customary to write the following headers: | |||
{| class="wikitable" | |||
|- | |||
| Examples || sample of use | |||
|- | |||
| Panics || scenarios when this method panics | |||
|- | |||
| Errors || the error types that may be returned | |||
|- | |||
| Safety || if function is <code>unsafe</code>, why | |||
|- | |||
|} | |||
<syntaxhighlight lang="rust"> | |||
</syntaxhighlight> | </syntaxhighlight> | ||
</blockquote><!-- Common Headers --> | |||
</blockquote><!-- Doc Comments --> | </blockquote><!-- Doc Comments --> |
Revision as of 21:14, 9 February 2023
Regular Comments
// inline comment
/* multiline * comment */
Annotation Comments
Variable assignments can be annotated
// This number is used because... let magic_number = 123;
Doc Comments
Generate/View Docs
cargo doc --open # build, and view docs (current project, and it's dependencies)Basics
doc-comments are written in markdown, and code-blocks default to rust as the language.
assertions written in doc-comments are run with your test-suite.//! # My Module (doc-comment for enclosing item) //! //! This module does foo, and bar, and baz. //! (can be used for functions, but not idiomatic) //! (often used for crates) /// Feeds the cat (doc-comment for following-item) /// /// # Examples /// /// ``` /// let name = "mycat"; /// let success = feed(name); /// assert!(success); /// ``` fn feed_cat(name: &str) -> bool { println!("hi") }Common Headers
It's customary to write the following headers:
Examples sample of use Panics scenarios when this method panics Errors the error types that may be returned Safety if function is unsafe
, why