nordic-dev.net/rust
nordic-dev.net/rust
2
0
Fork 0
mirror of https://github.com/rust-lang/rust.git synced 2024-11-22 14:55:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

macros: update comments

Browse Source 
Various small changes to comments, like wrapping code in backticks,
changing comments to doc comments and adding newlines.

Signed-off-by: David Wood <david.wood@huawei.com>
This commit is contained in:
David Wood 2022-03-30 03:00:54 +01:00
parent d5119c5b9f
commit 2bf64d6483
1 changed files with 34 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

61
compiler/rustc_macros/src/session_diagnostic.rs
View File

@ -5,8 +5,9 @@ use syn::spanned::Spanned;
use std::collections::{BTreeSet, HashMap}; use std::collections::{BTreeSet, HashMap};
/// Implements #[derive(SessionDiagnostic)], which allows for errors to be specified as a struct, independent /// Implements `#[derive(SessionDiagnostic)]`, which allows for errors to be specified as a struct,
/// from the actual diagnostics emitting code. /// independent from the actual diagnostics emitting code.
///
/// ```ignore (pseudo-rust) /// ```ignore (pseudo-rust)
/// # extern crate rustc_errors; /// # extern crate rustc_errors;
/// # use rustc_errors::Applicability; /// # use rustc_errors::Applicability;
@ -28,6 +29,7 @@ use std::collections::{BTreeSet, HashMap};
/// pub opt_sugg: Option<(Span, Applicability)> /// pub opt_sugg: Option<(Span, Applicability)>
/// } /// }
/// ``` /// ```
///
/// Then, later, to emit the error: /// Then, later, to emit the error:
/// ///
/// ```ignore (pseudo-rust) /// ```ignore (pseudo-rust)
@ -47,10 +49,10 @@ pub fn session_diagnostic_derive(s: synstructure::Structure<'_>) -> proc_macro2:
SessionDiagnosticDerive::new(diag, sess, s).into_tokens() SessionDiagnosticDerive::new(diag, sess, s).into_tokens()
} }
// Checks whether the type name of `ty` matches `name`. /// Checks whether the type name of `ty` matches `name`.
// ///
// Given some struct at a::b::c::Foo, this will return true for c::Foo, b::c::Foo, or /// Given some struct at `a::b::c::Foo`, this will return true for `c::Foo`, `b::c::Foo`, or
// a::b::c::Foo. This reasonably allows qualified names to be used in the macro. /// `a::b::c::Foo`. This reasonably allows qualified names to be used in the macro.
fn type_matches_path(ty: &syn::Type, name: &[&str]) -> bool { fn type_matches_path(ty: &syn::Type, name: &[&str]) -> bool {
if let syn::Type::Path(ty) = ty { if let syn::Type::Path(ty) = ty {
ty.path ty.path
@ -65,7 +67,7 @@ fn type_matches_path(ty: &syn::Type, name: &[&str]) -> bool {
} }
} }
/// The central struct for constructing the as_error method from an annotated struct. /// The central struct for constructing the `as_error` method from an annotated struct.
struct SessionDiagnosticDerive<'a> { struct SessionDiagnosticDerive<'a> {
structure: synstructure::Structure<'a>, structure: synstructure::Structure<'a>,
builder: SessionDiagnosticDeriveBuilder<'a>, builder: SessionDiagnosticDeriveBuilder<'a>,
@ -77,7 +79,7 @@ impl std::convert::From<syn::Error> for SessionDiagnosticDeriveError {
} }
} }
/// Equivalent to rustc:errors::diagnostic::DiagnosticId, except stores the quoted expression to /// Equivalent to `rustc:errors::diagnostic::DiagnosticId`, except stores the quoted expression to
/// initialise the code with. /// initialise the code with.
enum DiagnosticId { enum DiagnosticId {
Error(proc_macro2::TokenStream), Error(proc_macro2::TokenStream),
@ -109,9 +111,10 @@ fn span_err(span: impl proc_macro::MultiSpan, msg: &str) -> proc_macro::Diagnost
Diagnostic::spanned(span, proc_macro::Level::Error, msg) Diagnostic::spanned(span, proc_macro::Level::Error, msg)
} }
/// For methods that return a Result<_, SessionDiagnosticDeriveError>: emit a diagnostic on /// For methods that return a `Result<_, SessionDiagnosticDeriveError>`:
/// span $span with msg $msg (and, optionally, perform additional decoration using the FnOnce ///
/// passed in `diag`). Then, return Err(ErrorHandled). /// Emit a diagnostic on span `$span` with msg `$msg` (optionally performing additional decoration
/// using the `FnOnce` passed in `diag`) and return `Err(ErrorHandled)`.
macro_rules! throw_span_err { macro_rules! throw_span_err {
($span:expr, $msg:expr) => {{ throw_span_err!($span, $msg, |diag| diag) }}; ($span:expr, $msg:expr) => {{ throw_span_err!($span, $msg, |diag| diag) }};
($span:expr, $msg:expr, $f:expr) => {{ ($span:expr, $msg:expr, $f:expr) => {{
@ -119,8 +122,8 @@ macro_rules! throw_span_err {
}}; }};
} }
/// When possible, prefer using throw_span_err! over using this function directly. This only exists /// When possible, prefer using `throw_span_err!` over using this function directly. This only
/// as a function to constrain `f` to an impl FnOnce. /// exists as a function to constrain `f` to an `impl FnOnce`.
fn _throw_span_err( fn _throw_span_err(
span: impl proc_macro::MultiSpan, span: impl proc_macro::MultiSpan,
msg: &str, msg: &str,
@ -240,8 +243,8 @@ impl<'a> SessionDiagnosticDerive<'a> {
} }
} }
/// Field information passed to the builder. Deliberately omits attrs to discourage the generate_* /// Field information passed to the builder. Deliberately omits attrs to discourage the
/// methods from walking the attributes themselves. /// `generate_*` methods from walking the attributes themselves.
struct FieldInfo<'a> { struct FieldInfo<'a> {
vis: &'a syn::Visibility, vis: &'a syn::Visibility,
binding: &'a synstructure::BindingInfo<'a>, binding: &'a synstructure::BindingInfo<'a>,
@ -250,22 +253,22 @@ struct FieldInfo<'a> {
} }
/// Tracks persistent information required for building up the individual calls to diagnostic /// Tracks persistent information required for building up the individual calls to diagnostic
/// methods for the final generated method. This is a separate struct to SessionDerive only to be /// methods for the final generated method. This is a separate struct to `SessionDiagnosticDerive`
/// able to destructure and split self.builder and the self.structure up to avoid a double mut /// only to be able to destructure and split `self.builder` and the `self.structure` up to avoid a
/// borrow later on. /// double mut borrow later on.
struct SessionDiagnosticDeriveBuilder<'a> { struct SessionDiagnosticDeriveBuilder<'a> {
/// Name of the session parameter that's passed in to the as_error method. /// Name of the session parameter that's passed in to the `as_error` method.
sess: syn::Ident, sess: syn::Ident,
/// Store a map of field name to its corresponding field. This is built on construction of the /// Store a map of field name to its corresponding field. This is built on construction of the
/// derive builder. /// derive builder.
fields: HashMap<String, &'a syn::Field>, fields: HashMap<String, &'a syn::Field>,
/// The identifier to use for the generated DiagnosticBuilder instance. /// The identifier to use for the generated `DiagnosticBuilder` instance.
diag: syn::Ident, diag: syn::Ident,
/// Whether this is a lint or an error. This dictates how the diag will be initialised. Span /// Whether this is a lint or an error. This dictates how the diag will be initialised. `Span`
/// stores at what Span the kind was first set at (for error reporting purposes, if the kind /// stores at what `Span` the kind was first set at (for error reporting purposes, if the kind
/// was multiply specified). /// was multiply specified).
kind: Option<(DiagnosticId, proc_macro2::Span)>, kind: Option<(DiagnosticId, proc_macro2::Span)>,
} }
@ -560,7 +563,8 @@ impl<'a> SessionDiagnosticDeriveBuilder<'a> {
} }
/// In the strings in the attributes supplied to this macro, we want callers to be able to /// In the strings in the attributes supplied to this macro, we want callers to be able to
/// reference fields in the format string. Take this, for example: /// reference fields in the format string. For example:
///
/// ```ignore (not-usage-example) /// ```ignore (not-usage-example)
/// struct Point { /// struct Point {
/// #[error = "Expected a point greater than ({x}, {y})"] /// #[error = "Expected a point greater than ({x}, {y})"]
@ -568,12 +572,15 @@ impl<'a> SessionDiagnosticDeriveBuilder<'a> {
/// y: i32, /// y: i32,
/// } /// }
/// ``` /// ```
/// We want to automatically pick up that {x} refers `self.x` and {y} refers to `self.y`, then ///
/// generate this call to format!: /// We want to automatically pick up that `{x}` refers `self.x` and `{y}` refers to `self.y`,
/// then generate this call to `format!`:
///
/// ```ignore (not-usage-example) /// ```ignore (not-usage-example)
/// format!("Expected a point greater than ({x}, {y})", x = self.x, y = self.y) /// format!("Expected a point greater than ({x}, {y})", x = self.x, y = self.y)
/// ``` /// ```
/// This function builds the entire call to format!. ///
/// This function builds the entire call to `format!`.
fn build_format(&self, input: &str, span: proc_macro2::Span) -> proc_macro2::TokenStream { fn build_format(&self, input: &str, span: proc_macro2::Span) -> proc_macro2::TokenStream {
// This set is used later to generate the final format string. To keep builds reproducible, // This set is used later to generate the final format string. To keep builds reproducible,
// the iteration order needs to be deterministic, hence why we use a BTreeSet here instead // the iteration order needs to be deterministic, hence why we use a BTreeSet here instead
@ -646,7 +653,7 @@ impl<'a> SessionDiagnosticDeriveBuilder<'a> {
} }
} }
/// If `ty` is an Option, returns Some(inner type). Else, returns None. /// If `ty` is an Option, returns `Some(inner type)`, otherwise returns `None`.
fn option_inner_ty(ty: &syn::Type) -> Option<&syn::Type> { fn option_inner_ty(ty: &syn::Type) -> Option<&syn::Type> {
if type_matches_path(ty, &["std", "option", "Option"]) { if type_matches_path(ty, &["std", "option", "Option"]) {
if let syn::Type::Path(ty_path) = ty { if let syn::Type::Path(ty_path) = ty {