From 3dec18a681c7ff4eef2d4eb5e62c0278b6110e22 Mon Sep 17 00:00:00 2001 From: topecongiro Date: Sun, 31 Mar 2019 19:13:15 +0900 Subject: [PATCH] Add doc comment --- config_proc_macro/src/attrs.rs | 16 +++++ config_proc_macro/src/config_type.rs | 2 + config_proc_macro/src/item_enum.rs | 1 + src/config/lists.rs | 10 +-- src/config/options.rs | 97 ++++++++++++++++------------ 5 files changed, 81 insertions(+), 45 deletions(-) diff --git a/config_proc_macro/src/attrs.rs b/config_proc_macro/src/attrs.rs index cd0a701479b0..0df68772ae63 100644 --- a/config_proc_macro/src/attrs.rs +++ b/config_proc_macro/src/attrs.rs @@ -1,23 +1,39 @@ +//! This module provides utilities for handling attributes on variants +//! of `config_type` enum. Currently there are two types of attributes +//! that could appear on the variants of `config_type` enum: `doc_hint` +//! and `value`. Both comes in the form of name-value pair whose value +//! is string literal. + +/// Returns the value of the first `doc_hint` attribute in the given slice or +/// `None` if `doc_hint` attribute is not available. pub fn find_doc_hint(attrs: &[syn::Attribute]) -> Option { attrs.iter().filter_map(doc_hint).next() } +/// Returns `true` if the given attribute is a `doc_hint` attribute. pub fn is_doc_hint(attr: &syn::Attribute) -> bool { is_attr_name_value(attr, "doc_hint") } +/// Returns a string literal value if the given attribute is `doc_hint` +/// attribute or `None` otherwise. pub fn doc_hint(attr: &syn::Attribute) -> Option { get_name_value_str_lit(attr, "doc_hint") } +/// Returns the value of the first `value` attribute in the given slice or +/// `None` if `value` attribute is not available. pub fn find_config_value(attrs: &[syn::Attribute]) -> Option { attrs.iter().filter_map(config_value).next() } +/// Returns a string literal value if the given attribute is `value` +/// attribute or `None` otherwise. pub fn config_value(attr: &syn::Attribute) -> Option { get_name_value_str_lit(attr, "value") } +/// Returns `true` if the given attribute is a `value` attribute. pub fn is_config_value(attr: &syn::Attribute) -> bool { is_attr_name_value(attr, "value") } diff --git a/config_proc_macro/src/config_type.rs b/config_proc_macro/src/config_type.rs index daff3f5c61cf..93a78b8463ec 100644 --- a/config_proc_macro/src/config_type.rs +++ b/config_proc_macro/src/config_type.rs @@ -3,6 +3,8 @@ use proc_macro2::TokenStream; use crate::item_enum::define_config_type_on_enum; use crate::item_struct::define_config_type_on_struct; +/// Defines `config_type` on enum or struct. +// FIXME: Implement this on struct. pub fn define_config_type(input: &syn::Item) -> TokenStream { match input { syn::Item::Struct(st) => define_config_type_on_struct(st), diff --git a/config_proc_macro/src/item_enum.rs b/config_proc_macro/src/item_enum.rs index acb00a99cb4e..eb7254ada7a8 100644 --- a/config_proc_macro/src/item_enum.rs +++ b/config_proc_macro/src/item_enum.rs @@ -6,6 +6,7 @@ use crate::utils::*; type Variants = syn::punctuated::Punctuated; +/// Defines and implements `config_type` enum. pub fn define_config_type_on_enum(em: &syn::ItemEnum) -> syn::Result { let syn::ItemEnum { vis, diff --git a/src/config/lists.rs b/src/config/lists.rs index 86faab57d16a..0270bd0eb0b3 100644 --- a/src/config/lists.rs +++ b/src/config/lists.rs @@ -28,15 +28,15 @@ impl DefinitiveListTactic { /// their comments. #[config_type] pub enum ListTactic { - // One item per row. + /// One item per row. Vertical, - // All items on one row. + /// All items on one row. Horizontal, - // Try Horizontal layout, if that fails then vertical. + /// Try Horizontal layout, if that fails then vertical. HorizontalVertical, - // HorizontalVertical with a soft limit of n characters. + /// HorizontalVertical with a soft limit of n characters. LimitedHorizontalVertical(usize), - // Pack as many items as possible per row over (possibly) many rows. + /// Pack as many items as possible per row over (possibly) many rows. Mixed, } diff --git a/src/config/options.rs b/src/config/options.rs index e8a26a4aeea4..9b0060bfdb6b 100644 --- a/src/config/options.rs +++ b/src/config/options.rs @@ -11,10 +11,14 @@ use crate::config::Config; #[config_type] pub enum NewlineStyle { - Auto, // Auto-detect based on the raw source input - Windows, // \r\n - Unix, // \n - Native, // \r\n in Windows, \n on other platforms + /// Auto-detect based on the raw source input. + Auto, + /// Force CRLF (`\r\n`). + Windows, + /// Force CR (`\n). + Unix, + /// `\r\n` in Windows, `\n`` on other platforms. + Native, } impl NewlineStyle { @@ -74,58 +78,66 @@ impl NewlineStyle { } #[config_type] +/// Where to put the opening brace of items (`fn`, `impl`, etc.). pub enum BraceStyle { + /// Put the opening brace on the next line. AlwaysNextLine, + /// Put the opening brace on the same line, if possible. PreferSameLine, - // Prefer same line except where there is a where-clause, in which case force - // the brace to the next line. + /// Prefer the same line except where there is a where-clause, in which + /// case force the brace to be put on the next line. SameLineWhere, } #[config_type] +/// Where to put the opening brace of conditional expressions (`if`, `match`, etc.). pub enum ControlBraceStyle { - // K&R style, Rust community default + /// K&R style, Rust community default AlwaysSameLine, - // Stroustrup style + /// Stroustrup style ClosingNextLine, - // Allman style + /// Allman style AlwaysNextLine, } #[config_type] +/// How to indent. pub enum IndentStyle { - // First line on the same line as the opening brace, all lines aligned with - // the first line. + /// First line on the same line as the opening brace, all lines aligned with + /// the first line. Visual, - // First line is on a new line and all lines align with block indent. + /// First line is on a new line and all lines align with **block** indent. Block, } #[config_type] +/// How to place a list-like items. pub enum Density { - // Fit as much on one line as possible. + /// Fit as much on one line as possible. Compressed, - // Use more lines. + /// Use more lines. Tall, - // Place every item on a separate line. + /// Place every item on a separate line. Vertical, } #[config_type] +/// Spacing around type combinators. pub enum TypeDensity { - // No spaces around "=" and "+" + /// No spaces around "=" and "+" Compressed, - // Spaces around " = " and " + " + /// Spaces around " = " and " + " Wide, } #[config_type] +/// To what extent does rustfmt pursue its heuristics? pub enum Heuristics { - // Turn off any heuristics + /// Turn off any heuristics Off, - // Turn on max heuristics + /// Turn on max heuristics Max, - // Use Rustfmt's defaults + /// Use Rustfmt's defaults Default, } @@ -147,42 +159,44 @@ pub enum ReportTactic { Never, } -// What Rustfmt should emit. Mostly corresponds to the `--emit` command line -// option. +/// What Rustfmt should emit. Mostly corresponds to the `--emit` command line +/// option. #[config_type] pub enum EmitMode { - // Emits to files. + /// Emits to files. Files, - // Writes the output to stdout. + /// Writes the output to stdout. Stdout, - // Displays how much of the input file was processed + /// Displays how much of the input file was processed Coverage, - // Unfancy stdout + /// Unfancy stdout Checkstyle, - // Output the changed lines (for internal value only) + /// Output the changed lines (for internal value only) 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. Used for `--check`. + /// 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. Used for `--check`. Diff, } -// Client-preference for coloured output. +/// Client-preference for coloured output. #[config_type] pub enum Color { - // Always use color, whether it is a piped or terminal output + /// Always use color, whether it is a piped or terminal output Always, - // Never use color + /// Never use color Never, - // Automatically use color, if supported by terminal + /// Automatically use color, if supported by terminal Auto, } #[config_type] +/// rustfmt format style version. pub enum Version { - // 1.x.y + /// 1.x.y. When specified, rustfmt will format in the same style as 1.0.0. One, - // 2.x.y + /// 2.x.y. When specified, rustfmt will formatin the the latest style. Two, } @@ -197,13 +211,14 @@ impl Color { } } -// How chatty should Rustfmt be? +/// How chatty should Rustfmt be? #[config_type] pub enum Verbosity { - // Emit more. + /// Emit more. Verbose, + /// Default. Normal, - // Emit as little as possible. + /// Emit as little as possible. Quiet, } @@ -369,14 +384,16 @@ pub trait CliOptions { fn config_path(&self) -> Option<&Path>; } -// The edition of the compiler (RFC 2052) +/// The edition of the syntax and semntics of code (RFC 2052). #[config_type] pub enum Edition { #[value = "2015"] #[doc_hint = "2015"] + /// Edition 2015. Edition2015, #[value = "2018"] #[doc_hint = "2018"] + /// Edition 2018. Edition2018, }