macros: add more documentation comments

Documentation comments are always good.

Signed-off-by: David Wood <david.wood@huawei.com>

compiler/rustc_macros/src/diagnostics/diagnostic.rs

@@ -14,7 +14,7 @@ use std::collections::HashMap;
 use syn::{spanned::Spanned, Attribute, Meta, MetaList, MetaNameValue, Type};
 use synstructure::Structure;
 
-/// The central struct for constructing the `as_error` method from an annotated struct.
+/// The central struct for constructing the `into_diagnostic` method from an annotated struct.
 pub(crate) struct SessionDiagnosticDerive<'a> {
     structure: Structure<'a>,
     builder: SessionDiagnosticDeriveBuilder,

compiler/rustc_macros/src/diagnostics/subdiagnostic.rs

@@ -16,6 +16,8 @@ use std::str::FromStr;
 use syn::{spanned::Spanned, Meta, MetaList, MetaNameValue};
 use synstructure::{BindingInfo, Structure, VariantInfo};
 
+/// `Applicability` of a suggestion - mirrors `rustc_errors::Applicability` - and used to represent
+/// the user's selection of applicability if specified in an attribute.
 enum Applicability {
     MachineApplicable,
     MaybeIncorrect,
@@ -56,6 +58,7 @@ impl quote::ToTokens for Applicability {
     }
 }
 
+/// Which kind of suggestion is being created?
 #[derive(Clone, Copy)]
 enum SubdiagnosticSuggestionKind {
     /// `#[suggestion]`
@@ -68,6 +71,7 @@ enum SubdiagnosticSuggestionKind {
     Verbose,
 }
 
+/// Which kind of subdiagnostic is being created from a variant?
 #[derive(Clone, Copy)]
 enum SubdiagnosticKind {
     /// `#[label(...)]`
@@ -129,6 +133,7 @@ impl quote::IdentFragment for SubdiagnosticKind {
     }
 }
 
+/// The central struct for constructing the `add_to_diagnostic` method from an annotated struct.
 pub(crate) struct SessionSubdiagnosticDerive<'a> {
     structure: Structure<'a>,
     diag: syn::Ident,
@@ -210,6 +215,10 @@ impl<'a> SessionSubdiagnosticDerive<'a> {
     }
 }
 
+/// Tracks persistent information required for building up the call to add to the diagnostic
+/// for the final generated method. This is a separate struct to `SessionSubdiagnosticDerive`
+/// only to be able to destructure and split `self.builder` and the `self.structure` up to avoid a
+/// double mut borrow later on.
 struct SessionSubdiagnosticDeriveBuilder<'a> {
     /// The identifier to use for the generated `DiagnosticBuilder` instance.
     diag: &'a syn::Ident,

compiler/rustc_macros/src/diagnostics/utils.rs

@@ -102,6 +102,8 @@ pub(crate) struct FieldInfo<'a> {
     pub(crate) span: &'a proc_macro2::Span,
 }
 
+/// Small helper trait for abstracting over `Option` fields that contain a value and a `Span`
+/// for error reporting if they are set more than once.
 pub(crate) trait SetOnce<T> {
     fn set_once(&mut self, value: T);
 }
@@ -122,6 +124,7 @@ impl<T> SetOnce<(T, Span)> for Option<(T, Span)> {
 }
 
 pub(crate) trait HasFieldMap {
+    /// Returns the binding for the field with the given name, if it exists on the type.
     fn get_field_binding(&self, field: &String) -> Option<&TokenStream>;
 
     /// In the strings in the attributes supplied to this macro, we want callers to be able to