documentation

Author: nrc

src/checkstyle.rs

@@ -13,6 +13,10 @@ use std::path::Path;
 
 use rustfmt_diff::{DiffLine, Mismatch};
 
+/// The checkstyle header - should be emitted before the output of Rustfmt.
+///
+/// Note that emitting checkstyle output is not stable and may removed in a
+/// future version of Rustfmt.
 pub fn header() -> String {
     let mut xml_heading = String::new();
     xml_heading.push_str("<?xml version=\"1.0\" encoding=\"utf-8\"?>");
@@ -21,6 +25,10 @@ pub fn header() -> String {
     xml_heading
 }
 
+/// The checkstyle footer - should be emitted after the output of Rustfmt.
+///
+/// Note that emitting checkstyle output is not stable and may removed in a
+/// future version of Rustfmt.
 pub fn footer() -> String {
     "</checkstyle>\n".to_owned()
 }

src/config/file_lines.rs

@@ -27,6 +27,7 @@ pub struct LineRange {
     pub hi: usize,
 }
 
+/// Defines the name of an input - either a file or stdin.
 #[derive(Clone, Debug, Eq, PartialEq, Hash, Ord, PartialOrd)]
 pub enum FileName {
     Real(PathBuf),

src/config/mod.rs

@@ -146,6 +146,8 @@ create_config! {
     make_backup: bool, false, false, "Backup changed files";
 }
 
+/// Load a config by checking the client-supplied options and if appropriate, the
+/// file system (including searching the file system for overrides).
 pub fn load_config<O: CliOptions>(
     file_path: Option<&Path>,
     options: Option<O>,

src/config/options.rs

@@ -167,6 +167,8 @@ configuration_option_enum! { ReportTactic:
     Never,
 }
 
+// What Rustfmt should emit. Mostly corresponds to the `--emit` command line
+// option.
 configuration_option_enum! { EmitMode:
     // Emits to files.
     Files,
@@ -180,10 +182,11 @@ configuration_option_enum! { EmitMode:
     ModifiedLines,
     // Checks if a diff can be generated. If so, rustfmt outputs a diff and quits with exit code 1.
     // This option is designed to be run in CI where a non-zero exit signifies non-standard code
-    // formatting.
+    // formatting. Used for `--check`.
     Diff,
 }
 
+// Client-preference for coloured output.
 configuration_option_enum! { Color:
     // Always use color, whether it is a piped or terminal output
     Always,
@@ -194,6 +197,7 @@ configuration_option_enum! { Color:
 }
 
 impl Color {
+    /// Whether we should use a coloured terminal.
     pub fn use_colored_tty(&self) -> bool {
         match self {
             Color::Always => true,
@@ -203,6 +207,7 @@ impl Color {
     }
 }
 
+// How chatty should Rustfmt be?
 configuration_option_enum! { Verbosity:
     // Emit more.
     Verbose,
@@ -322,6 +327,8 @@ impl ::std::str::FromStr for IgnoreList {
     }
 }
 
+/// Maps client-supplied options to Rustfmt's internals, mostly overriding
+/// values in a config with values from the command line.
 pub trait CliOptions {
     fn apply_to(self, config: &mut Config);
     fn config_path(&self) -> Option<&Path>;

src/config/summary.rs

@@ -11,6 +11,7 @@
 use std::default::Default;
 use std::time::{Duration, Instant};
 
+/// A summary of a Rustfmt run.
 #[derive(Debug, Default, Clone, Copy)]
 pub struct Summary {
     // Encountered e.g. an IO error.
@@ -25,7 +26,7 @@ pub struct Summary {
     // Failed a check, such as the license check or other opt-in checking.
     has_check_errors: bool,
 
-    // Formatted code differs from existing code (--check only).
+    /// Formatted code differs from existing code (--check only).
     pub has_diff: bool,
 
     // Keeps track of time spent in parsing and formatting steps.
@@ -106,6 +107,7 @@ impl Summary {
             || self.has_diff)
     }
 
+    /// Combine two summaries together.
     pub fn add(&mut self, other: Summary) {
         self.has_operational_errors |= other.has_operational_errors;
         self.has_formatting_errors |= other.has_formatting_errors;

src/lib.rs

@@ -102,33 +102,38 @@ pub(crate) type FileMap = Vec<FileRecord>;
 
 pub(crate) type FileRecord = (FileName, String);
 
+/// The various errors that can occur during formatting. Note that not all of
+/// these can currently be propagated to clients.
 #[derive(Fail, Debug)]
 pub enum ErrorKind {
-    // Line has exceeded character limit (found, maximum)
+    /// Line has exceeded character limit (found, maximum).
     #[fail(
         display = "line formatted, but exceeded maximum width \
                    (maximum: {} (see `max_width` option), found: {})",
         _0,
         _1
     )]
     LineOverflow(usize, usize),
-    // Line ends in whitespace
+    /// Line ends in whitespace.
     #[fail(display = "left behind trailing whitespace")]
     TrailingWhitespace,
-    // TODO or FIXME item without an issue number
+    /// TODO or FIXME item without an issue number.
     #[fail(display = "found {}", _0)]
     BadIssue(Issue),
-    // License check has failed
+    /// License check has failed.
     #[fail(display = "license check failed")]
     LicenseCheck,
-    // Used deprecated skip attribute
+    /// Used deprecated skip attribute.
     #[fail(display = "`rustfmt_skip` is deprecated; use `rustfmt::skip`")]
     DeprecatedAttr,
-    // Used a rustfmt:: attribute other than skip
+    /// Used a rustfmt:: attribute other than skip.
     #[fail(display = "invalid attribute")]
     BadAttr,
+    /// An io error during reading or writing.
     #[fail(display = "io error: {}", _0)]
     IoError(io::Error),
+    /// The user mandated a version and the current version of Rustfmt does not
+    /// satisfy that requirement.
     #[fail(display = "Version mismatch")]
     VersionMismatch,
 }
@@ -204,6 +209,9 @@ impl FormattingError {
     }
 }
 
+/// Reports on any issues that occurred during a run of Rustfmt.
+///
+/// Can be reported to the user via its `Display` implementation of `print_fancy`.
 #[derive(Clone)]
 pub struct FormatReport {
     // Maps stringified file paths to their associated formatting errors.
@@ -266,10 +274,13 @@ impl FormatReport {
             .sum()
     }
 
+    /// Whether any warnings or errors are present in the report.
     pub fn has_warnings(&self) -> bool {
         self.warning_count() > 0
     }
 
+    /// Print the report to a terminal using colours and potentially other
+    /// fancy output.
     pub fn fancy_print(
         &self,
         mut t: Box<term::Terminal<Output = io::Stderr>>,
@@ -758,6 +769,8 @@ pub enum Input {
     Text(String),
 }
 
+/// The main entry point for Rustfmt. Formats the given input according to the
+/// given config. `out` is only necessary if required by the configuration.
 pub fn format_input<T: Write>(
     input: Input,
     config: &Config,