mirror of
https://github.com/alrayyes/wiki.git
synced 2024-11-22 11:36:23 +00:00
114 lines
2.5 KiB
Markdown
114 lines
2.5 KiB
Markdown
---
|
||
date: 20200827
|
||
id: f4c04f44-c7c3-4fa0-a4d6-e78995257b9c
|
||
title: Rust Comments
|
||
---
|
||
|
||
# Basics
|
||
|
||
In Rust, the idiomatic comment style starts a comment with two slashes,
|
||
and the comment continues until the end of the line. For comments that
|
||
extend beyond a single line, you’ll need to include // on each line,
|
||
like this:
|
||
|
||
``` rust
|
||
// So we’re doing something complicated here, long enough that we need
|
||
// multiple lines of comments to do it! Whew! Hopefully, this comment will
|
||
// explain what’s going on.
|
||
```
|
||
|
||
Comments can also be placed at the end of lines containing code:
|
||
|
||
``` rust
|
||
fn main() {
|
||
println!("tralala") // This prints something
|
||
}
|
||
```
|
||
|
||
But if you're a sane person you'll comment above the code you're
|
||
annotating
|
||
|
||
``` rust
|
||
// This prints something
|
||
fn main() {
|
||
println!("tralala")
|
||
}
|
||
```
|
||
|
||
# Documentation comments
|
||
|
||
## */*
|
||
|
||
This is like phpdoc, but for Rust. Documentation comments use three
|
||
slashes `///` and support Markdown notation:
|
||
|
||
``` rust
|
||
/// Adds one to the number given.
|
||
///
|
||
/// # Examples
|
||
///
|
||
/// ```
|
||
/// let arg = 5;
|
||
/// let answer = my_crate::add_one(arg);
|
||
///
|
||
/// assert_eq!(6, answer);
|
||
/// ```
|
||
pub fn add_one(x: i32) -> i32 {
|
||
x + 1
|
||
}
|
||
```
|
||
|
||
Run `cargo doc` to generate HTML documentation from the comments.
|
||
`cargo doc --open` will open documentation in the browser.
|
||
|
||
### Commonly used sections
|
||
|
||
1. Panics
|
||
|
||
The scenarios in which the function being documented could panic.
|
||
Callers of the function who don’t want their programs to panic
|
||
should make sure they don’t call the function in these situations.
|
||
|
||
2. Errors
|
||
|
||
If the function returns a `Result`, describing the kinds of errors
|
||
that might occur and what conditions might cause those errors to be
|
||
returned can be helpful to callers so they can write code to handle
|
||
the different kinds of errors in different ways.
|
||
|
||
3. Safety
|
||
|
||
If the function is `unsafe` to call, there should be a section
|
||
explaining why the function is unsafe and covering the invariants
|
||
that the function expects callers to uphold.
|
||
|
||
## //!
|
||
|
||
This is used for general comments:
|
||
|
||
``` rust
|
||
//! # My Crate
|
||
//!
|
||
//! `my_crate` is a collection of utilities to make performing certain
|
||
//! calculations more convenient.
|
||
|
||
/// Adds one to the number given.
|
||
// --snip--
|
||
///
|
||
/// # Examples
|
||
///
|
||
/// ```
|
||
/// let arg = 5;
|
||
/// let answer = my_crate::add_one(arg);
|
||
///
|
||
/// assert_eq!(6, answer);
|
||
/// ```
|
||
pub fn add_one(x: i32) -> i32 {
|
||
x + 1
|
||
}
|
||
```
|
||
|
||
# Changes
|
||
|
||
- [Linking To Items By Name](20201119170237-linking_to_items_by_name)
|
||
- [Search Aliases](20201119170710-search_aliases)
|