--- title: "13.8 Reading documentation" description: "How to actually read a method signature you've never seen on docs.rs and the standard library docs: a practical skill that makes you self-sufficient." url: "https://learnrust.net/chapter-13/reading-documentation/" last_updated: "2026-06-13" --- # 13.8 Reading documentation No course can teach you every function in the standard library, let alone every crate on crates.io. What it can teach is the skill that makes the rest unnecessary: reading documentation well enough to figure out an unfamiliar function yourself. This is one of the highest-leverage things in the whole course. Master it and you stop needing tutorials for individual functions, because you can read the official docs and just *know*. ## Where the docs live Two sites, one layout. The standard library is documented at `doc.rust-lang.org/std` (also openable offline with `rustup doc`). Every crate published to crates.io is automatically documented at `docs.rs/`. Both are generated by `cargo doc` (lesson [13.7](https://learnrust.net/chapter-13/documentation-comments/)), so they navigate identically: a sidebar of modules and types, a search box at the top, and a page per item showing its signature, description, and examples. Learn to read one and you've learned to read them all. The search box is the fastest way in. Searching the std docs for `parse`, `push_str`, or `HashMap` jumps straight to the item. Get in the habit of searching the docs before searching the web; the answer is usually one keystroke closer than you think. ## Reading a signature The core skill is reading a function or method signature, because the signature tells you almost everything: what it needs, what it gives back, and whether it can fail. Take a method you've used, `str::parse`, whose real signature is: ```rust pub fn parse(&self) -> Result where F: FromStr, ``` That looks dense, but everything in it is something this course has taught. Walk it left to right. `pub fn parse` is a public method named `parse`. `` is a generic type parameter (chapter 15, just ahead): the type to parse *into*, which is why you write `parse::()` or annotate the binding. `(&self)` means it borrows the string immutably (lesson [9.1](https://learnrust.net/chapter-9/references-borrowing-a-value/)); it reads the text and doesn't take ownership. `-> Result` is the return: a `Result` (lesson [12.2](https://learnrust.net/chapter-12/result/)), `Ok` with the parsed `F` on success or an error on failure, which is exactly why lesson [5.6](https://learnrust.net/chapter-5/parsing-strings-into-numbers/) had you handle the failure case. The `where F: FromStr` is a constraint you'll fully understand after chapter 16: `F` must be a type that knows how to be parsed from a string. You can read this signature *today*, because each piece is a concept you already hold. > **Key insight** > > A Rust signature is a contract you can read. `&self` versus `&mut self` versus `self` tells you whether a method reads, modifies, or consumes (lesson [10.5](https://learnrust.net/chapter-10/methods-and-impl-blocks/)). A `Result` or `Option` return tells you it can fail or come up empty, and the compiler will make you handle that. The parameter types tell you what you must hand over and whether you keep ownership. You often don't need the prose at all: the types alone say what the function does to your data. This is the practical reward for nine chapters of types, ownership, and borrowing. ## What to look for on a docs page A productive way to read an item's page, roughly in order: Start with the **signature** and read it as above; it frames everything else. Read the **one-line summary** for the intent. Check for a **`# Panics`** section: does this function panic on some inputs (lesson [12.1](https://learnrust.net/chapter-12/panic-and-unrecoverable-errors/))? An indexing method might; a `get` method might return `Option` instead. Check **`# Errors`** if it returns `Result`, to learn what failure means. Then read an **example**, which is usually the fastest way to see the calling convention, and remember it's a tested example (lesson [13.7](https://learnrust.net/chapter-13/documentation-comments/)), so it definitely compiles. For a type like `Vec` or `HashMap`, the page lists every method grouped by `impl` block, plus the traits it implements (chapter 16), which tell you what it can do generically (can it be printed? compared? iterated?). You don't read these pages top to bottom; you search or scan for the capability you need and read just that method's entry. ## Worked habit: "how do I uppercase a string?" Concretely: you want to uppercase a `String` and don't know the method. Search the std docs for `str` or `String`, scan the method list for something promising, find `to_uppercase`, and read its signature: `pub fn to_uppercase(&self) -> String`. The `&self` says it borrows your string (doesn't consume it), and the `-> String` says it hands back a *new* owned string rather than modifying yours in place (which makes sense: uppercasing can change length, lesson [4.8](https://learnrust.net/chapter-4/char-and-unicode/)). You now know how to call it and what you'll get back, without a tutorial. That loop, search, read the signature, glance at an example, is the entire skill, and it scales from `str` to any crate you'll ever pull in. > **Best practice** > > When you reach for an unfamiliar method, read its signature *first* and predict its behavior before reading the prose, then use the description to confirm. This builds the muscle that eventually lets you skip the prose entirely for routine functions. It also catches the common mistakes early: a method that returns `Option` is telling you to handle the empty case, and a `&mut self` method is telling you you'll need a `mut` binding. ## Quiz time **Question #1** Where are the standard library and third-party crates documented, and why do both sites look the same?
Show solution The standard library is at `doc.rust-lang.org/std` (or offline via `rustup doc`); crates published to crates.io are at `docs.rs/`. Both look and navigate the same because both are generated by `cargo doc` from doc comments (lesson [13.7](https://learnrust.net/chapter-13/documentation-comments/)), so learning to read one teaches you to read all of them.
**Question #2** From the signature `pub fn get(&self, index: usize) -> Option<&T>`, what can you tell about this method without reading any prose?
Show solution It's a public method that borrows `self` immutably (`&self`, so it only reads), takes a `usize` index (lesson [4.3](https://learnrust.net/chapter-4/isize-usize-and-integer-literals/)), and returns `Option<&T>`, meaning it gives back a *borrowed* element wrapped in `Option`. The `Option` tells you it handles out-of-range access by returning `None` rather than panicking, so you must handle the empty case. (Contrast `[]` indexing, which panics out of bounds, lesson [18.2](https://learnrust.net/chapter-18/vec-creating-and-updating/).)
**Question #3** You need to find out whether a string contains a substring. Describe the steps you'd take in the docs.
Show solution Search the std docs for `str` (or `String`), scan its method list for something like `contains`, and read its signature: `pub fn contains(&self, pat: P) -> bool` (roughly). The `&self` shows it borrows the string, and `-> bool` shows it answers yes/no without consuming or modifying. Glance at the example to confirm the calling form, then use it. No tutorial required.
That closes the chapter's last lesson: you can now organize code, control its visibility, split it across files and crates, drive Cargo, and read the docs for anything you haven't met. The summary and quiz are next, and then chapter 14 turns the doc-test teaser into the real thing, Rust's built-in testing framework, where the `lib.rs` split from lesson [13.5](https://learnrust.net/chapter-13/binary-and-library-crates/) finally pays off. ## Sitemap See the full [sitemap](https://learnrust.net/sitemap.md) for all pages.