From b5b11d307559465f4ca617c034839862902c4d84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Th=C3=A9o=20LUDWIG?= Date: Tue, 20 Feb 2024 23:11:44 +0100 Subject: [PATCH] docs: add chapter 14 --- chapter_14_cargo_and_crates/README.md | 90 ++++++++++++++++++++++++++- 1 file changed, 89 insertions(+), 1 deletion(-) diff --git a/chapter_14_cargo_and_crates/README.md b/chapter_14_cargo_and_crates/README.md index c6e58ca..aefe88a 100644 --- a/chapter_14_cargo_and_crates/README.md +++ b/chapter_14_cargo_and_crates/README.md @@ -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 +``` + +### 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).