From 9731278d2a1cf680cc7939242d440a982f1f49be Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Fri, 14 Feb 2020 04:49:25 -0800 Subject: [PATCH] Wrap comments at 80 characters (#593) I think 70 is too agressive, especially since it includes indentation when determining line length. --- rustfmt.toml | 4 ++-- src/config.rs | 12 +++++------- src/expression.rs | 8 ++++---- src/justfile.rs | 12 +++++------- src/lexer.rs | 23 +++++++++++------------ src/line.rs | 3 +-- src/module.rs | 11 +++++------ src/name.rs | 4 ++-- src/node.rs | 7 +++---- src/parser.rs | 38 ++++++++++++++++---------------------- src/platform.rs | 8 ++++---- src/platform_interface.rs | 11 +++++------ src/positional.rs | 36 ++++++++++++++++-------------------- src/recipe.rs | 9 ++++----- src/search_config.rs | 11 +++++------ src/show_whitespace.rs | 3 +-- src/summary.rs | 18 +++++++++--------- src/tree.rs | 14 ++++++-------- tests/working_directory.rs | 25 ++++++++++++------------- 19 files changed, 116 insertions(+), 141 deletions(-) diff --git a/rustfmt.toml b/rustfmt.toml index d8f79c1..3b14719 100644 --- a/rustfmt.toml +++ b/rustfmt.toml @@ -1,4 +1,4 @@ -comment_width = 70 +comment_width = 80 edition = "2018" error_on_line_overflow = true error_on_unformatted = true @@ -13,7 +13,7 @@ newline_style = "Unix" normalize_comments = true overflow_delimited_expr = true reorder_impl_items = true -required_version = "1.4.11" +required_version = "1.4.12" struct_field_align_threshold = 20 tab_spaces = 2 unstable_features = true diff --git a/src/config.rs b/src/config.rs index 50129be..9c6dadc 100644 --- a/src/config.rs +++ b/src/config.rs @@ -552,10 +552,9 @@ impl Config { } } - // Declaring this outside of the nested loops will probably be more - // efficient, but it creates all sorts of lifetime issues with - // variables inside the loops. If this is inlined like the - // docs say, it shouldn't make any difference. + // Declaring this outside of the nested loops will probably be more efficient, + // but it creates all sorts of lifetime issues with variables inside the loops. + // If this is inlined like the docs say, it shouldn't make any difference. let print_doc = |doc| { print!( " {:padding$}{} {}", @@ -641,9 +640,8 @@ mod tests { use pretty_assertions::assert_eq; - // This test guards against unintended changes to the argument parser. - // We should have proper tests for all the flags, but this will do - // for now. + // This test guards against unintended changes to the argument parser. We should + // have proper tests for all the flags, but this will do for now. #[test] fn help() { const EXPECTED_HELP: &str = "just v0.5.8 diff --git a/src/expression.rs b/src/expression.rs index b9776de..a4595c3 100644 --- a/src/expression.rs +++ b/src/expression.rs @@ -1,9 +1,9 @@ use crate::common::*; -/// An expression. Note that the Just language grammar has both an -/// `expression` production of additions (`a + b`) and values, and a -/// `value` production of all other value types (for example strings, -/// function calls, and parenthetical groups). +/// An expression. Note that the Just language grammar has both an `expression` +/// production of additions (`a + b`) and values, and a `value` production of +/// all other value types (for example strings, function calls, and +/// parenthetical groups). /// /// The parser parses both values and expressions into `Expression`s. #[derive(PartialEq, Debug)] diff --git a/src/justfile.rs b/src/justfile.rs index d199042..e4c9cb3 100644 --- a/src/justfile.rs +++ b/src/justfile.rs @@ -301,13 +301,11 @@ mod tests { } } - // this test exists to make sure that shebang recipes - // run correctly. although this script is still - // executed by a shell its behavior depends on the value of a - // variable and continuing even though a command fails, - // whereas in plain recipes variables are not available - // in subsequent lines and execution stops when a line - // fails + // This test exists to make sure that shebang recipes run correctly. Although + // this script is still executed by a shell its behavior depends on the value of + // a variable and continuing even though a command fails, whereas in plain + // recipes variables are not available in subsequent lines and execution stops + // when a line fails. run_error! { name: run_shebang, src: " diff --git a/src/lexer.rs b/src/lexer.rs index 4cf9861..eeca8b6 100644 --- a/src/lexer.rs +++ b/src/lexer.rs @@ -5,12 +5,12 @@ use TokenKind::*; /// Just language lexer /// -/// The lexer proceeds character-by-character, as opposed to using -/// regular expressions to lex tokens or semi-tokens at a time. As a -/// result, it is verbose and straightforward. Just used to have a -/// regex-based lexer, which was slower and generally godawful. -/// However, this should not be taken as a slight against regular -/// expressions, the lexer was just idiosyncratically bad. +/// The lexer proceeds character-by-character, as opposed to using regular +/// expressions to lex tokens or semi-tokens at a time. As a result, it is +/// verbose and straightforward. Just used to have a regex-based lexer, which +/// was slower and generally godawful. However, this should not be taken as a +/// slight against regular expressions, the lexer was just idiosyncratically +/// bad. pub(crate) struct Lexer<'src> { /// Source text src: &'src str, @@ -65,8 +65,8 @@ impl<'src> Lexer<'src> { } } - /// Advance over the character in `self.next`, updating - /// `self.token_end` accordingly. + /// Advance over the character in `self.next`, updating `self.token_end` + /// accordingly. fn advance(&mut self) -> CompilationResult<'src, ()> { match self.next { Some(c) => { @@ -138,8 +138,8 @@ impl<'src> Lexer<'src> { !self.indentation().is_empty() } - /// Create a new token with `kind` whose lexeme - /// is between `self.token_start` and `self.token_end` + /// Create a new token with `kind` whose lexeme is between `self.token_start` + /// and `self.token_end` fn token(&mut self, kind: TokenKind) { self.tokens.push(Token { offset: self.token_start.offset, @@ -177,8 +177,7 @@ impl<'src> Lexer<'src> { fn error(&self, kind: CompilationErrorKind<'src>) -> CompilationError<'src> { // Use the in-progress token span as the location of the error. - // The width of the error site to highlight depends on the kind of - // error: + // The width of the error site to highlight depends on the kind of error: let length = match kind { // highlight ' or " UnterminatedString => 1, diff --git a/src/line.rs b/src/line.rs index 6335abd..b03897c 100644 --- a/src/line.rs +++ b/src/line.rs @@ -1,7 +1,6 @@ use crate::common::*; -/// A single line in a recipe body, consisting of any number of -/// `Fragment`s. +/// A single line in a recipe body, consisting of any number of `Fragment`s. #[derive(Debug, PartialEq)] pub(crate) struct Line<'src> { pub(crate) fragments: Vec>, diff --git a/src/module.rs b/src/module.rs index 7bba998..9f453ee 100644 --- a/src/module.rs +++ b/src/module.rs @@ -1,13 +1,12 @@ use crate::common::*; -/// A module, the top-level type produced by the parser. So-named -/// because although at present, all justfiles consist of a single -/// module, in the future we will likely have multi-module and -/// multi-file justfiles. +/// A module, the top-level type produced by the parser. So-named because +/// although at present, all justfiles consist of a single module, in the future +/// we will likely have multi-module and multi-file justfiles. /// /// Not all successful parses result in valid justfiles, so additional -/// consistency checks and name resolution are performed by the -/// `Analyzer`, which produces a `Justfile` from a `Module`. +/// consistency checks and name resolution are performed by the `Analyzer`, +/// which produces a `Justfile` from a `Module`. #[derive(Debug)] pub(crate) struct Module<'src> { /// Items in the justfile diff --git a/src/name.rs b/src/name.rs index e58a542..f1030b4 100644 --- a/src/name.rs +++ b/src/name.rs @@ -1,7 +1,7 @@ use crate::common::*; -/// A name. This is effectively just a `Token` of kind `Identifier`, -/// but we give it its own type for clarity. +/// A name. This is effectively just a `Token` of kind `Identifier`, but we give +/// it its own type for clarity. #[derive(Debug, Clone, Copy, PartialEq, Eq, Ord, PartialOrd)] pub(crate) struct Name<'src> { pub(crate) offset: usize, diff --git a/src/node.rs b/src/node.rs index 5878c29..c55d018 100644 --- a/src/node.rs +++ b/src/node.rs @@ -1,10 +1,9 @@ use crate::common::*; -/// Methods commmon to all AST nodes. Currently only used in parser -/// unit tests. +/// Methods commmon to all AST nodes. Currently only used in parser unit tests. pub(crate) trait Node<'src> { - /// Construct an untyped tree of atoms representing this Node. This - /// function, and `Tree` type, are only used in parser unit tests. + /// Construct an untyped tree of atoms representing this Node. This function, + /// and `Tree` type, are only used in parser unit tests. fn tree(&self) -> Tree<'src>; } diff --git a/src/parser.rs b/src/parser.rs index 56b52e7..fed78cd 100644 --- a/src/parser.rs +++ b/src/parser.rs @@ -4,24 +4,20 @@ use TokenKind::*; /// Just language parser /// -/// The parser is a (hopefully) straightforward recursive descent -/// parser. +/// The parser is a (hopefully) straightforward recursive descent parser. /// -/// It uses a few tokens of lookahead to disambiguate different -/// constructs. +/// It uses a few tokens of lookahead to disambiguate different constructs. /// -/// The `expect_*` and `presume_`* methods are similar in that they -/// assert the type of unparsed tokens and consume them. However, upon -/// encountering an unexpected token, the `expect_*` methods return an -/// unexpected token error, whereas the `presume_*` tokens return an -/// internal error. +/// The `expect_*` and `presume_`* methods are similar in that they assert the +/// type of unparsed tokens and consume them. However, upon encountering an +/// unexpected token, the `expect_*` methods return an unexpected token error, +/// whereas the `presume_*` tokens return an internal error. /// -/// The `presume_*` methods are used when the token stream has been -/// inspected in some other way, and thus encountering an unexpected -/// token is a bug in Just, and not a syntax error. +/// The `presume_*` methods are used when the token stream has been inspected in +/// some other way, and thus encountering an unexpected token is a bug in Just, +/// and not a syntax error. /// -/// All methods starting with `parse_*` parse and return a language -/// construct. +/// All methods starting with `parse_*` parse and return a language construct. pub(crate) struct Parser<'tokens, 'src> { /// Source tokens tokens: &'tokens [Token<'src>], @@ -129,8 +125,8 @@ impl<'tokens, 'src> Parser<'tokens, 'src> { Err(self.internal_error("`Parser::advance()` advanced past end of token stream")?) } - /// Return the next token if it is of kind `expected`, otherwise, - /// return an unexpected token error + /// Return the next token if it is of kind `expected`, otherwise, return an + /// unexpected token error fn expect(&mut self, expected: TokenKind) -> CompilationResult<'src, Token<'src>> { if let Some(token) = self.accept(expected)? { Ok(token) @@ -161,8 +157,8 @@ impl<'tokens, 'src> Parser<'tokens, 'src> { self.expect(Eol).map(|_| ()).expected(&[Eof]) } - /// Return an internal error if the next token is not of kind - /// `Identifier` with lexeme `lexeme`. + /// Return an internal error if the next token is not of kind `Identifier` + /// with lexeme `lexeme`. fn presume_name(&mut self, lexeme: &str) -> CompilationResult<'src, ()> { let next = self.advance()?; @@ -182,8 +178,7 @@ impl<'tokens, 'src> Parser<'tokens, 'src> { } } - /// Return an internal error if the next token is not of kind - /// `kind`. + /// Return an internal error if the next token is not of kind `kind`. fn presume(&mut self, kind: TokenKind) -> CompilationResult<'src, Token<'src>> { let next = self.advance()?; @@ -197,8 +192,7 @@ impl<'tokens, 'src> Parser<'tokens, 'src> { } } - /// Return an internal error if the next token is not one of kinds - /// `kinds`. + /// Return an internal error if the next token is not one of kinds `kinds`. fn presume_any(&mut self, kinds: &[TokenKind]) -> CompilationResult<'src, Token<'src>> { let next = self.advance()?; if !kinds.contains(&next.kind) { diff --git a/src/platform.rs b/src/platform.rs index 2d5076f..d90e126 100644 --- a/src/platform.rs +++ b/src/platform.rs @@ -71,14 +71,14 @@ impl PlatformInterface for Platform { } fn set_execute_permission(_path: &Path) -> Result<(), io::Error> { - // it is not necessary to set an execute permission on a script on - // windows, so this is a nop + // it is not necessary to set an execute permission on a script on windows, so + // this is a nop Ok(()) } fn signal_from_exit_status(_exit_status: process::ExitStatus) -> Option { - // The rust standard library does not expose a way to extract a signal - // from a windows process exit status, so just return None + // The rust standard library does not expose a way to extract a signal from a + // windows process exit status, so just return None None } diff --git a/src/platform_interface.rs b/src/platform_interface.rs index 36e0fab..5b958ad 100644 --- a/src/platform_interface.rs +++ b/src/platform_interface.rs @@ -1,8 +1,8 @@ use crate::common::*; pub(crate) trait PlatformInterface { - /// Construct a command equivalent to running the script at `path` - /// with the shebang line `shebang` + /// Construct a command equivalent to running the script at `path` with the + /// shebang line `shebang` fn make_shebang_command( path: &Path, working_directory: &Path, @@ -13,11 +13,10 @@ pub(crate) trait PlatformInterface { /// Set the execute permission on the file pointed to by `path` fn set_execute_permission(path: &Path) -> Result<(), io::Error>; - /// Extract the signal from a process exit status, if it was - /// terminated by a signal + /// Extract the signal from a process exit status, if it was terminated by a + /// signal fn signal_from_exit_status(exit_status: process::ExitStatus) -> Option; - /// Translate a path from a "native" path to a path the interpreter - /// expects + /// Translate a path from a "native" path to a path the interpreter expects fn to_shell_path(working_directory: &Path, path: &Path) -> Result; } diff --git a/src/positional.rs b/src/positional.rs index a93f838..04923d1 100644 --- a/src/positional.rs +++ b/src/positional.rs @@ -1,35 +1,31 @@ use crate::common::*; -/// A struct containing the parsed representation of positional -/// command-line arguments, i.e. arguments that are not flags, -/// options, or the subcommand. +/// A struct containing the parsed representation of positional command-line +/// arguments, i.e. arguments that are not flags, options, or the subcommand. /// -/// The DSL of positional arguments is fairly complex and mostly -/// accidental. There are three possible components: overrides, -/// a search directory, and the rest: +/// The DSL of positional arguments is fairly complex and mostly accidental. +/// There are three possible components: overrides, a search directory, and the +/// rest: /// /// - Overrides are of the form `NAME=.*` /// -/// - After overrides comes a single optional search directory -/// argument. This is either '.', '..', or an argument that contains -/// a `/`. +/// - After overrides comes a single optional search directory argument. This is +/// either '.', '..', or an argument that contains a `/`. /// -/// If the argument contains a `/`, everything before and including -/// the slash is the search directory, and everything after is added -/// to the rest. +/// If the argument contains a `/`, everything before and including the slash +/// is the search directory, and everything after is added to the rest. /// /// - Everything else is an argument. /// -/// Overrides set the values of top-level variables in the justfile -/// being invoked and are a convenient way to override settings. +/// Overrides set the values of top-level variables in the justfile being +/// invoked and are a convenient way to override settings. /// -/// For modes that do not take other arguments, the search directory -/// argument determines where to begin searching for the justfile. -/// This allows command lines like `just -l ..` and `just ../build` to -/// find the same justfile. +/// For modes that do not take other arguments, the search directory argument +/// determines where to begin searching for the justfile. This allows command +/// lines like `just -l ..` and `just ../build` to find the same justfile. /// -/// For modes that do take other arguments, the search argument is -/// simply prepended to rest. +/// For modes that do take other arguments, the search argument is simply +/// prepended to rest. #[cfg_attr(test, derive(PartialEq, Debug))] pub struct Positional { /// Overrides from values of the form `[a-zA-Z_][a-zA-Z0-9_-]*=.*` diff --git a/src/recipe.rs b/src/recipe.rs index 6613a90..fb266a5 100644 --- a/src/recipe.rs +++ b/src/recipe.rs @@ -2,8 +2,8 @@ use crate::common::*; use std::process::{ExitStatus, Stdio}; -/// Return a `RuntimeError::Signal` if the process was terminated by a -/// signal, otherwise return an `RuntimeError::UnknownFailure` +/// Return a `RuntimeError::Signal` if the process was terminated by a signal, +/// otherwise return an `RuntimeError::UnknownFailure` fn error_from_signal( recipe: &str, line_number: Option, @@ -120,9 +120,8 @@ impl<'src, D> Recipe<'src, D> { // add the shebang text += &evaluated_lines[0]; text += "\n"; - // add blank lines so that lines in the generated script - // have the same line number as the corresponding lines - // in the justfile + // add blank lines so that lines in the generated script have the same line + // number as the corresponding lines in the justfile for _ in 1..(self.line_number() + 2) { text += "\n" } diff --git a/src/search_config.rs b/src/search_config.rs index 40dd220..97f62f9 100644 --- a/src/search_config.rs +++ b/src/search_config.rs @@ -3,15 +3,14 @@ use crate::common::*; /// Controls how `just` will search for the justfile. #[derive(Debug, PartialEq)] pub(crate) enum SearchConfig { - /// Recursively search for the justfile upwards from the - /// invocation directory to the root, setting the working - /// directory to the directory in which the justfile is - /// found. + /// Recursively search for the justfile upwards from the invocation directory + /// to the root, setting the working directory to the directory in which the + /// justfile is found. FromInvocationDirectory, /// As in `Invocation`, but start from `search_directory`. FromSearchDirectory { search_directory: PathBuf }, - /// Use user-specified justfile, with the working directory - /// set to the directory that contains it. + /// Use user-specified justfile, with the working directory set to the + /// directory that contains it. WithJustfile { justfile: PathBuf }, /// Use user-specified justfile and working directory. WithJustfileAndWorkingDirectory { diff --git a/src/show_whitespace.rs b/src/show_whitespace.rs index d70bc74..dd24f07 100644 --- a/src/show_whitespace.rs +++ b/src/show_whitespace.rs @@ -1,7 +1,6 @@ use crate::common::*; -/// String wrapper that uses nonblank characters to display spaces and -/// tabs +/// String wrapper that uses nonblank characters to display spaces and tabs pub struct ShowWhitespace<'str>(pub &'str str); impl<'str> Display for ShowWhitespace<'str> { diff --git a/src/summary.rs b/src/summary.rs index 38d8f2f..afc4d1c 100644 --- a/src/summary.rs +++ b/src/summary.rs @@ -1,16 +1,16 @@ //! Justfile summary creation, for testing purposes only. //! -//! The contents of this module are not bound by any stability -//! guarantees. Breaking changes may be introduced at any time. +//! The contents of this module are not bound by any stability guarantees. +//! Breaking changes may be introduced at any time. //! -//! The main entry point into this module is the `summary` function, -//! which parses a justfile at a given path and produces a `Summary` -//! object, which broadly captures the functionality of the parsed -//! justfile, or an error message. +//! The main entry point into this module is the `summary` function, which +//! parses a justfile at a given path and produces a `Summary` object, which +//! broadly captures the functionality of the parsed justfile, or an error +//! message. //! -//! This functionality is intended to be used with `janus`, a tool for -//! ensuring that changes to just do not inadvertently break or -//! change the interpretation of existing justfiles. +//! This functionality is intended to be used with `janus`, a tool for ensuring +//! that changes to just do not inadvertently break or change the interpretation +//! of existing justfiles. use std::{collections::BTreeMap, fs, io, path::Path}; diff --git a/src/tree.rs b/src/tree.rs index 3fe82de..f7821cf 100644 --- a/src/tree.rs +++ b/src/tree.rs @@ -2,10 +2,9 @@ use crate::common::*; use std::mem; -/// Construct a `Tree` from a symbolic expression literal. This macro, -/// and the Tree type, are only used in the Parser unit tests, as a -/// concise notation representing the expected results of parsing a -/// given string. +/// Construct a `Tree` from a symbolic expression literal. This macro, and the +/// Tree type, are only used in the Parser unit tests, as a concise notation +/// representing the expected results of parsing a given string. macro_rules! tree { { ($($child:tt)*) @@ -63,8 +62,7 @@ impl<'text> Tree<'text> { Tree::atom(format!("\"{}\"", contents.as_ref())) } - /// Push a child node into self, turning it into a List if it was an - /// Atom + /// Push a child node into self, turning it into a List if it was an Atom pub(crate) fn push(self, tree: impl Into>) -> Tree<'text> { match self { Tree::List(mut children) => { @@ -75,8 +73,8 @@ impl<'text> Tree<'text> { } } - /// Extend a self with a tail of Trees, turning self into a List if - /// it was an Atom + /// Extend a self with a tail of Trees, turning self into a List if it was an + /// Atom pub(crate) fn extend(self, tail: I) -> Tree<'text> where I: IntoIterator, diff --git a/tests/working_directory.rs b/tests/working_directory.rs index 75592cb..c003a7b 100644 --- a/tests/working_directory.rs +++ b/tests/working_directory.rs @@ -20,8 +20,8 @@ const DATA: &str = "OK"; const WANT: &str = "shebang: OK\nexpression: OK\ndefault: OK\nlinewise: OK\n"; -/// Test that just runs with the correct working directory when -/// invoked with `--justfile` but not `--working-directory` +/// Test that just runs with the correct working directory when invoked with +/// `--justfile` but not `--working-directory` #[test] fn justfile_without_working_directory() -> Result<(), Box> { let tmp = tmptree! { @@ -46,9 +46,8 @@ fn justfile_without_working_directory() -> Result<(), Box> { Ok(()) } -/// Test that just runs with the correct working directory when -/// invoked with `--justfile` but not `--working-directory`, and -/// justfile path has no parent +/// Test that just runs with the correct working directory when invoked with +/// `--justfile` but not `--working-directory`, and justfile path has no parent #[test] fn justfile_without_working_directory_relative() -> Result<(), Box> { let tmp = tmptree! { @@ -74,8 +73,8 @@ fn justfile_without_working_directory_relative() -> Result<(), Box> { Ok(()) } -/// Test that just invokes commands from the directory in which the -/// justfile is found +/// Test that just invokes commands from the directory in which the justfile is +/// found #[test] fn change_working_directory_to_search_justfile_parent() -> Result<(), Box> { let tmp = tmptree! { @@ -100,8 +99,8 @@ fn change_working_directory_to_search_justfile_parent() -> Result<(), Box Result<(), Box> { let tmp = tmptree! { @@ -130,8 +129,8 @@ fn justfile_and_working_directory() -> Result<(), Box> { Ok(()) } -/// Test that just runs with the correct working directory when -/// invoked with `--justfile` but not `--working-directory` +/// Test that just runs with the correct working directory when invoked with +/// `--justfile` but not `--working-directory` #[test] fn search_dir_child() -> Result<(), Box> { let tmp = tmptree! { @@ -158,8 +157,8 @@ fn search_dir_child() -> Result<(), Box> { Ok(()) } -/// Test that just runs with the correct working directory when -/// invoked with `--justfile` but not `--working-directory` +/// Test that just runs with the correct working directory when invoked with +/// `--justfile` but not `--working-directory` #[test] fn search_dir_parent() -> Result<(), Box> { let tmp = tmptree! {