docs(rustfix): comments for diagnostic JSON output

Most doc comments are copied from rust-lang/rust repo.

The doc for each item is hand-written as there is no comment in the
original place.

Author: weihanglo

crates/rustfix/src/diagnostics.rs

@@ -1,9 +1,12 @@
-//! Rustc Diagnostic JSON Output
+//! Rustc Diagnostic JSON Output.
 //!
-//! The following data types are copied from [rust-lang/rust](https://github.com/rust-lang/rust/blob/de78655bca47cac8e783dbb563e7e5c25c1fae40/src/libsyntax/json.rs)
+//! The following data types are copied from [rust-lang/rust](https://github.com/rust-lang/rust/blob/4fd68eb47bad1c121417ac4450b2f0456150db86/compiler/rustc_errors/src/json.rs).
+//!
+//! For examples of the JSON output, see JSON fixture files under `tests/` directory.
 
 use serde::Deserialize;
 
+/// The root diagnostic JSON output emitted by the compiler.
 #[derive(Clone, Deserialize, Debug, Hash, Eq, PartialEq)]
 pub struct Diagnostic {
     /// The primary error message.
@@ -14,12 +17,11 @@ pub struct Diagnostic {
     pub spans: Vec<DiagnosticSpan>,
     /// Associated diagnostic messages.
     pub children: Vec<Diagnostic>,
-    /// The message as rustc would render it. Currently this is only
-    /// `Some` for "suggestions", but eventually it will include all
-    /// snippets.
+    /// The message as rustc would render it.
     pub rendered: Option<String>,
 }
 
+/// Span information of a diagnostic item.
 #[derive(Clone, Deserialize, Debug, Hash, Eq, PartialEq)]
 pub struct DiagnosticSpan {
     pub file_name: String,
@@ -39,23 +41,43 @@ pub struct DiagnosticSpan {
     /// Label that should be placed at this location (if any)
     label: Option<String>,
     /// If we are suggesting a replacement, this will contain text
-    /// that should be sliced in atop this span. You may prefer to
-    /// load the fully rendered version from the parent `Diagnostic`,
-    /// however.
+    /// that should be sliced in atop this span.
     pub suggested_replacement: Option<String>,
+    /// If the suggestion is approximate
     pub suggestion_applicability: Option<Applicability>,
     /// Macro invocations that created the code at this span, if any.
     expansion: Option<Box<DiagnosticSpanMacroExpansion>>,
 }
 
+/// Indicates the confidence in the correctness of a suggestion.
+///
+/// All suggestions are marked with an `Applicability`. Tools use the applicability of a suggestion
+/// to determine whether it should be automatically applied or if the user should be consulted
+/// before applying the suggestion.
 #[derive(Copy, Clone, Debug, PartialEq, Deserialize, Hash, Eq)]
 pub enum Applicability {
+    /// The suggestion is definitely what the user intended, or maintains the exact meaning of the code.
+    /// This suggestion should be automatically applied.
+    ///
+    /// In case of multiple `MachineApplicable` suggestions (whether as part of
+    /// the same `multipart_suggestion` or not), all of them should be
+    /// automatically applied.
     MachineApplicable,
-    HasPlaceholders,
+
+    /// The suggestion may be what the user intended, but it is uncertain. The suggestion should
+    /// result in valid Rust code if it is applied.
     MaybeIncorrect,
+
+    /// The suggestion contains placeholders like `(...)` or `{ /* fields */ }`. The suggestion
+    /// cannot be applied automatically because it will not result in valid Rust code. The user
+    /// will need to fill in the placeholders.
+    HasPlaceholders,
+
+    /// The applicability of the suggestion is unknown.
     Unspecified,
 }
 
+/// Span information of a single line.
 #[derive(Clone, Deserialize, Debug, Eq, PartialEq, Hash)]
 pub struct DiagnosticSpanLine {
     pub text: String,
@@ -66,6 +88,7 @@ pub struct DiagnosticSpanLine {
     pub highlight_end: usize,
 }
 
+/// Span information for macro expansions.
 #[derive(Clone, Deserialize, Debug, Eq, PartialEq, Hash)]
 struct DiagnosticSpanMacroExpansion {
     /// span where macro was applied to generate this code; note that
@@ -80,6 +103,9 @@ struct DiagnosticSpanMacroExpansion {
     def_site_span: Option<DiagnosticSpan>,
 }
 
+/// The error code emitted by the compiler. See [Rust error codes index].
+///
+/// [Rust error codes index]: https://doc.rust-lang.org/error_codes/error-index.html
 #[derive(Clone, Deserialize, Debug, Eq, PartialEq, Hash)]
 pub struct DiagnosticCode {
     /// The code itself.