mirror of
https://github.com/theoludwig/rust_book.git
synced 2024-12-08 00:45:41 +01:00
docs: add chapter 14
This commit is contained in:
parent
4716b4edb3
commit
b5b11d3075
@ -6,7 +6,7 @@
|
||||
|
||||
Cargo has 2 main profiles:
|
||||
|
||||
- `dev`: for development (used by default with `cargo build`)
|
||||
- `dev`: for development, to compile faster (used by default with `cargo build`)
|
||||
- `release`: for release (used with `cargo build --release`)
|
||||
|
||||
We can customize the `release` profile by adding a section to the `Cargo.toml` file:
|
||||
@ -19,6 +19,94 @@ opt-level = 0
|
||||
opt-level = 3
|
||||
```
|
||||
|
||||
## Making Useful Documentation Comments
|
||||
|
||||
**Documentation comments** use three slashes, **`///`**, instead of two, `//`, and **support Markdown** notation for formatting the text. They needs to be placed before the item they are documenting.
|
||||
|
||||
There are 4 sections that can be used in documentation comments:
|
||||
|
||||
- `# Examples`: to show examples of how to use the function (`cargo test` will run the examples).
|
||||
- `# Panics`: to describe under what conditions the function will panic.
|
||||
- `# Errors`: if the function returns a `Result`, then this section is used to describe the kinds of errors that might occur and in what situations.
|
||||
- `# Safety`: if the function is `unsafe` to call, then this section is used to explain why it is unsafe and what invariants the function expects callers to uphold.
|
||||
|
||||
We don't necessarily need all of these sections, but this is a checklist to remind you of the aspects of your code users will be interested in knowing about.
|
||||
|
||||
For example, documenting a `add_one` function in a crate named `my_crate`:
|
||||
|
||||
```rs
|
||||
/// 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
|
||||
}
|
||||
```
|
||||
|
||||
We can generate the documentation with `cargo doc` and open the generated documentation with `cargo doc --open`.
|
||||
|
||||
### Commenting Contained Items
|
||||
|
||||
The style of doc comment `//!` adds documentation to the item that contains the comments rather than to the items following the comments (typically used at the beginning of a crate or module).
|
||||
|
||||
For example, to add documentation that describes the purpose of the `my_crate` crate that contains the `add_one` function:
|
||||
|
||||
```rs
|
||||
//! # My Crate
|
||||
//!
|
||||
//! `my_crate` is a collection of utilities to make performing certain
|
||||
//! calculations more convenient.
|
||||
```
|
||||
|
||||
## Publishing a Crate to Crates.io
|
||||
|
||||
Packages can be published to [crates.io](https://crates.io/), the Rust community’s package registry.
|
||||
|
||||
To publish a crate, we need an account on [crates.io](https://crates.io/) and get an API token, then with the token, we can login:
|
||||
|
||||
```sh
|
||||
cargo login <api-token>
|
||||
```
|
||||
|
||||
### Package Metadata
|
||||
|
||||
Before publishing, we need to add some metadata in the `[package]` section of the crate’s `Cargo.toml` file.
|
||||
|
||||
For example, the `Cargo.toml` file for the `guessing_game` crate:
|
||||
|
||||
```toml
|
||||
[package]
|
||||
name = "guessing_game"
|
||||
version = "1.0.0"
|
||||
edition = "2021"
|
||||
description = "A fun game where you guess what number the computer has chosen."
|
||||
license = "MIT"
|
||||
|
||||
[dependencies]
|
||||
```
|
||||
|
||||
### Publishing Process
|
||||
|
||||
```sh
|
||||
$ cargo publish
|
||||
Updating crates.io index
|
||||
Packaging guessing_game v0.1.0 (file:///projects/guessing_game)
|
||||
Verifying guessing_game v0.1.0 (file:///projects/guessing_game)
|
||||
Compiling guessing_game v0.1.0
|
||||
(file:///projects/guessing_game/target/package/guessing_game-0.1.0)
|
||||
Finished dev [unoptimized + debuginfo] target(s) in 0.19s
|
||||
Uploading guessing_game v0.1.0 (file:///projects/guessing_game)
|
||||
```
|
||||
|
||||
## Cargo Workspaces
|
||||
|
||||
A **workspace** is a set of packages that share the same `Cargo.lock` and output directory. This means that all packages in the workspace will share the same dependencies and build output.
|
||||
|
||||
An example of a workspace with multiple packages: [github.com/theoludwig/advent_of_code_2023](https://github.com/theoludwig/advent_of_code_2023).
|
||||
|
Loading…
Reference in New Issue
Block a user