docs(rustfix): add more doc comments

crates/rustfix/src/lib.rs

@@ -1,22 +1,23 @@
 //! Library for applying diagnostic suggestions to source code.
 //!
-//! This is a low-level library. You pass it the JSON output from `rustc`, and
-//! you can then use it to apply suggestions to in-memory strings. This
-//! library doesn't execute commands, or read or write from the filesystem.
+//! This is a low-level library. You pass it the [JSON output] from `rustc`,
+//! and you can then use it to apply suggestions to in-memory strings.
+//! This library doesn't execute commands, or read or write from the filesystem.
 //!
 //! If you are looking for the [`cargo fix`] implementation, the core of it is
 //! located in [`cargo::ops::fix`].
 //!
 //! [`cargo fix`]: https://doc.rust-lang.org/cargo/commands/cargo-fix.html
 //! [`cargo::ops::fix`]: https://github.com/rust-lang/cargo/blob/master/src/cargo/ops/fix.rs
+//! [JSON output]: diagnostics
 //!
 //! The general outline of how to use this library is:
 //!
 //! 1. Call `rustc` and collect the JSON data.
 //! 2. Pass the json data to [`get_suggestions_from_json`].
 //! 3. Create a [`CodeFix`] with the source of a file to modify.
 //! 4. Call [`CodeFix::apply`] to apply a change.
-//! 5. Write the source back to disk.
+//! 5. Call [`CodeFix::finish`] to get the result and write it back to disk.
 
 use std::collections::HashSet;
 use std::ops::Range;
@@ -27,12 +28,20 @@ pub mod diagnostics;
 use crate::diagnostics::{Diagnostic, DiagnosticSpan};
 mod replace;
 
+/// A filter to control which suggestion should be applied.
 #[derive(Debug, Clone, Copy)]
 pub enum Filter {
+    /// For [`diagnostics::Applicability::MachineApplicable`] only.
     MachineApplicableOnly,
+    /// Everything is included. YOLO!
     Everything,
 }
 
+/// Collects code [`Suggestion`]s from one or more compiler diagnostic lines.
+///
+/// Fails if any of diagnostic line `input` is not a valid [`Diagnostic`] JSON.
+///
+/// * `only` --- only diagnostics with a set of error codes (e.g. `E0005`) would be collected.
 pub fn get_suggestions_from_json<S: ::std::hash::BuildHasher>(
     input: &str,
     only: &HashSet<String, S>,
@@ -70,20 +79,24 @@ impl std::fmt::Display for LineRange {
     }
 }
 
-#[derive(Debug, Clone, Hash, PartialEq, Eq)]
 /// An error/warning and possible solutions for fixing it
+#[derive(Debug, Clone, Hash, PartialEq, Eq)]
 pub struct Suggestion {
     pub message: String,
     pub snippets: Vec<Snippet>,
     pub solutions: Vec<Solution>,
 }
 
+/// Solution to a diagnostic item.
 #[derive(Debug, Clone, Hash, PartialEq, Eq)]
 pub struct Solution {
+    /// The error message of the diagnostic item.
     pub message: String,
+    /// Possible solutions to fix the error.
     pub replacements: Vec<Replacement>,
 }
 
+/// Represents code that will get replaced.
 #[derive(Debug, Clone, Hash, PartialEq, Eq)]
 pub struct Snippet {
     pub file_name: String,
@@ -95,12 +108,16 @@ pub struct Snippet {
     pub text: (String, String, String),
 }
 
+/// Represents a replacement of a `snippet`.
 #[derive(Debug, Clone, Hash, PartialEq, Eq)]
 pub struct Replacement {
+    /// Code snippet that gets replaced.
     pub snippet: Snippet,
+    /// The replacement of the snippet.
     pub replacement: String,
 }
 
+/// Parses a [`Snippet`] from a diagnostic span item.
 fn parse_snippet(span: &DiagnosticSpan) -> Option<Snippet> {
     // unindent the snippet
     let indent = span
@@ -168,6 +185,7 @@ fn parse_snippet(span: &DiagnosticSpan) -> Option<Snippet> {
     })
 }
 
+/// Converts a [`DiagnosticSpan`] into a [`Replacement`].
 fn collect_span(span: &DiagnosticSpan) -> Option<Replacement> {
     let snippet = parse_snippet(span)?;
     let replacement = span.suggested_replacement.clone()?;
@@ -177,6 +195,9 @@ fn collect_span(span: &DiagnosticSpan) -> Option<Replacement> {
     })
 }
 
+/// Collects code [`Suggestion`]s from a single compiler diagnostic line.
+///
+/// * `only` --- only diagnostics with a set of error codes (e.g. `E0005`) would be collected.
 pub fn collect_suggestions<S: ::std::hash::BuildHasher>(
     diagnostic: &Diagnostic,
     only: &HashSet<String, S>,
@@ -237,17 +258,26 @@ pub fn collect_suggestions<S: ::std::hash::BuildHasher>(
     }
 }
 
+/// Represents a code fix. This doesn't write to disks but is only in memory.
+///
+/// The general way to use this is:
+///
+/// 1. Feeds the source of a file to [`CodeFix::new`].
+/// 2. Calls [`CodeFix::apply`] to apply suggestions to the source code.
+/// 3. Calls [`CodeFix::finish`] to get the "fixed" code.
 pub struct CodeFix {
     data: replace::Data,
 }
 
 impl CodeFix {
+    /// Creates a `CodeFix` with the source of a file to modify.
     pub fn new(s: &str) -> CodeFix {
         CodeFix {
             data: replace::Data::new(s.as_bytes()),
         }
     }
 
+    /// Applies a suggestion to the code.
     pub fn apply(&mut self, suggestion: &Suggestion) -> Result<(), Error> {
         for sol in &suggestion.solutions {
             for r in &sol.replacements {
@@ -258,11 +288,13 @@ impl CodeFix {
         Ok(())
     }
 
+    /// Gets the result of the "fixed" code.
     pub fn finish(&self) -> Result<String, Error> {
         Ok(String::from_utf8(self.data.to_vec())?)
     }
 }
 
+/// Applies multiple `suggestions` to the given `code`.
 pub fn apply_suggestions(code: &str, suggestions: &[Suggestion]) -> Result<String, Error> {
     let mut fix = CodeFix::new(code);
     for suggestion in suggestions.iter().rev() {

crates/rustfix/src/replace.rs

@@ -5,10 +5,14 @@
 use anyhow::{anyhow, ensure, Error};
 use std::rc::Rc;
 
+/// Indicates the change state of a [`Span`].
 #[derive(Debug, Clone, PartialEq, Eq)]
 enum State {
+    /// The initial state. No change applied.
     Initial,
+    /// Has been replaced.
     Replaced(Rc<[u8]>),
+    /// Has been inserted.
     Inserted(Rc<[u8]>),
 }
 
@@ -18,19 +22,23 @@ impl State {
     }
 }
 
+/// Span with a change [`State`].
 #[derive(Debug, Clone, PartialEq, Eq)]
 struct Span {
     /// Start of this span in parent data
     start: usize,
     /// up to end excluding
     end: usize,
+    /// Whether the span is inserted, replaced or still fresh.
     data: State,
 }
 
 /// A container that allows easily replacing chunks of its data
 #[derive(Debug, Clone, Default)]
 pub struct Data {
+    /// Original data.
     original: Vec<u8>,
+    /// [`Span`]s covering the full range of the original data.
     parts: Vec<Span>,
 }
 

src/cargo/lib.rs

@@ -70,6 +70,11 @@
 //!   This is not directly depended upon with a `path` dependency; cargo uses the version from crates.io.
 //!   It is intended to be versioned and published independently of Rust's release system.
 //!   Whenever a change needs to be made, bump the version in Cargo.toml and `cargo publish` it manually, and then update cargo's `Cargo.toml` to depend on the new version.
+//! - [`rustfix`](https://crates.io/crates/rustfix)
+//!   ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/rustfix)):
+//!   This defines structures that represent fix suggestions from rustc,
+//!   as well as generates "fixed" code from suggestions.
+//!   Operations in `rustfix` are all in memory and won't write to disks.
 //! - [`cargo-test-support`](https://github.com/rust-lang/cargo/tree/master/crates/cargo-test-support)
 //!   ([nightly docs](https://doc.rust-lang.org/nightly/nightly-rustc/cargo_test_support/index.html)):
 //!   This contains a variety of code to support writing tests