Rust comments: Difference between revisions

From wikinotes
 
Line 23: Line 23:
= Doc Comments =
= Doc Comments =
<blockquote>
<blockquote>
== Generate/View Docs ==
There are two styles of doc-comments:
<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">
//! # My Module (doc-comment for enclosing item)
//! document enclosing item (typically used for crates, modules)
//!
//! 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)
/// document following item (typically used for objects, functions)
///
/// # Examples
///
/// ```
/// let name = "mycat";
/// let success = feed(name);
/// assert!(success);
/// ```
fn feed_cat(name: &str) -> bool {
    println!("hi")
}
</syntaxhighlight>
<syntaxhighlight lang="rust">
</syntaxhighlight>
</syntaxhighlight>
</blockquote><!-- Basics -->
== Common Headers ==
<blockquote>
It's customary to write the following headers:


{| class="wikitable"
For more details, see [[rust documentation]].
|-
| 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>
</blockquote><!-- Common Headers -->
</blockquote><!-- Doc Comments -->
</blockquote><!-- Doc Comments -->

Latest revision as of 21:17, 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

There are two styles of doc-comments: 

//! document enclosing item (typically used for crates, modules)

/// document following item (typically used for objects, functions)

For more details, see rust documentation.

Retrieved from "http://willpittman.net:8080/index.php?title=Rust_comments&oldid=33374"