diff --git a/crates/typst-syntax/src/ast.rs b/crates/typst-syntax/src/ast.rs index ae2ddd270..892040b7b 100644 --- a/crates/typst-syntax/src/ast.rs +++ b/crates/typst-syntax/src/ast.rs @@ -107,8 +107,7 @@ impl<'a> Decorator<'a> { self.0.cast_first_match().unwrap_or_default() } - /// The decorator's arguments. - /// Currently, they are always strings. + /// The decorator's arguments. Currently, they are always strings. pub fn arguments(self) -> impl DoubleEndedIterator> { self.0.children().filter_map(Str::from_untyped) } diff --git a/crates/typst-syntax/src/lexer.rs b/crates/typst-syntax/src/lexer.rs index a15f0a18a..0e4b5b4be 100644 --- a/crates/typst-syntax/src/lexer.rs +++ b/crates/typst-syntax/src/lexer.rs @@ -98,12 +98,12 @@ impl Lexer<'_> { /// Shared methods with all [`LexMode`]. impl Lexer<'_> { /// Proceed to the next token and return a [`SyntaxNode`] containing it. - /// Note the token could be a [trivia](SyntaxKind::is_trivia). - /// Also, the syntax node returned might not always be a leaf, but could - /// actually come with a subtree (could be an inner node). This happens - /// when it is preferred to perform parsing at the character level instead - /// of at the token level, as seen, for example, in - /// [`decorator`](Lexer::decorator). + /// + /// Note the token could be a [trivia](SyntaxKind::is_trivia). Also, the + /// syntax node returned might not always be a leaf, but could actually + /// come with a subtree (could be an inner node). This happens when it is + /// preferred to perform parsing at the character level instead of at the + /// token level, as seen, for example, in [`decorator`](Lexer::decorator). pub fn next(&mut self) -> SyntaxNode { if self.mode == LexMode::Raw { let Some((kind, end)) = self.raw.pop() else { @@ -144,17 +144,19 @@ impl Lexer<'_> { } /// Constructs an error node with the given message. - /// The node's text is taken from the given start position up to and + /// + /// The node's inner text is taken from the given start position up to and /// including the current cursor position. fn emit_error(&self, message: impl Into, start: usize) -> SyntaxNode { let text = self.s.from(start); SyntaxNode::error(SyntaxError::new(message), text) } - /// Converts a token into a syntax node based on its kind. - /// The node's text is taken from the given start position up to and + /// Converts a token into a syntax node based on its kind. Produces an + /// error node if there are errors. + /// + /// The node's inner text is taken from the given start position up to and /// including the current cursor position. - /// Produces an error node if there are errors. fn emit_token(&mut self, kind: SyntaxKind, start: usize) -> SyntaxNode { let text = self.s.from(start); if kind == SyntaxKind::End { @@ -216,7 +218,8 @@ impl Lexer<'_> { /// Decorator lexing and auxiliary methods. impl Lexer<'_> { /// Lexes and parses a decorator into a complete syntax subtree. - /// The lexer is fully responsible by the decorator, as it is simpler to + /// + /// The lexer is fully responsible for the decorator, as it is simpler to /// parse them at the character level, given they follow a very simple /// and rigid structure, in the form /// `/! decorator-name("string argument1", "string argument2")` @@ -228,12 +231,12 @@ impl Lexer<'_> { let current_start = self.s.cursor(); - // Ignore initial non-newline whitespaces + // Ignore initial non-newline whitespaces. if !self.s.eat_while(is_inline_whitespace).is_empty() { subtree.push(self.emit_token(SyntaxKind::Space, current_start)); } - // Lex the decorator name + // Lex the decorator name. let current_start = self.s.cursor(); if !self.s.eat_if(is_id_start) { self.s.eat_until(is_newline); @@ -246,7 +249,7 @@ impl Lexer<'_> { let decorator_name = self.decorator_name(current_start); subtree.push(self.emit_token(decorator_name, current_start)); - // Left parenthesis before decorator arguments + // Left parenthesis before decorator arguments. let current_start = self.s.cursor(); if !self.s.eat_if('(') { self.s.eat_until(is_newline); @@ -258,10 +261,10 @@ impl Lexer<'_> { subtree.push(self.emit_token(SyntaxKind::LeftParen, current_start)); - // Decorator arguments - // Keep reading until we find a right parenthesis or newline. - // We have to check the newline before eating (through '.peek()') to - // ensure it is not considered part of the decorator. + // Decorator arguments: + // Keep reading until we find a right parenthesis or newline. We have + // to check the newline before eating (through '.peek()') to ensure it + // is not considered part of the decorator. let mut current_start = self.s.cursor(); let mut expecting_comma = false; let mut finished = false; @@ -317,9 +320,9 @@ impl Lexer<'_> { } /// Lexes a decorator name. + /// /// A decorator name is an identifier within a specific subset of allowed - /// identifiers. - /// Currently, `allow` is the only valid decorator name. + /// identifiers. Currently, `allow` is the only valid decorator name. fn decorator_name(&mut self, start: usize) -> SyntaxKind { self.s.eat_while(is_id_continue); let ident = self.s.from(start); @@ -334,6 +337,7 @@ impl Lexer<'_> { } /// Lexes a string in a decorator. + /// /// Currently, such strings only allow a very restricted set of characters. /// These restrictions may be lifted in the future. fn decorator_string(&mut self) -> SyntaxKind { @@ -1075,8 +1079,7 @@ fn count_newlines(text: &str) -> usize { newlines } -/// Count newlines in text. -/// Only counts up to 2 newlines. +/// Count newlines in text. Only counts up to 2 newlines. pub(crate) fn count_capped_newlines(text: &str) -> u8 { let mut newlines = 0; let mut s = Scanner::new(text); diff --git a/crates/typst/src/diag.rs b/crates/typst/src/diag.rs index 7baedae1d..314efa1de 100644 --- a/crates/typst/src/diag.rs +++ b/crates/typst/src/diag.rs @@ -122,7 +122,7 @@ macro_rules! __warning { ) => { $crate::diag::SourceDiagnostic::warning( $span, - std::option::Option::Some($crate::diag::CompilerWarning::$id), + ::std::option::Option::Some($crate::diag::CompilerWarning::$id), $crate::diag::eco_format!($fmt, $($arg),*), ) $(.with_hint($crate::diag::eco_format!($hint, $($hint_arg),*)))* }; diff --git a/crates/typst/src/engine.rs b/crates/typst/src/engine.rs index 5a26ce886..5db2dbe0b 100644 --- a/crates/typst/src/engine.rs +++ b/crates/typst/src/engine.rs @@ -86,6 +86,7 @@ impl Engine<'_> { } /// Executes some code with a tracepoint for diagnostics. + /// /// The tracepoint is added to any diagnostics returned by the function, /// as well as any warnings emitted by it. pub fn tracepoint( @@ -187,6 +188,7 @@ impl Sink { } /// Extend the destination sink with the data from the source sink. + /// /// This calls a tracked function on the destination unless the source /// is fully empty (which is usually the case). pub fn extend_tracked(destination: &mut TrackedMut<'_, Self>, source: Sink) { @@ -239,9 +241,8 @@ impl Sink { } let Some(identifier) = &diag.identifier else { - // Can't suppress without an identifier. - // Therefore, retain the warning. - // It is not a duplicate due to the check above. + // Can't suppress without an identifier. Therefore, retain the + // warning. It is not a duplicate due to the check above. unsuppressed_warning_set.insert(hash); return true; }; @@ -282,13 +283,13 @@ impl Sink { /// Add a warning. pub fn warn(&mut self, warning: SourceDiagnostic) { // Check if warning is a duplicate. + // // Identical warnings with differing tracepoints are considered // separate because suppressing the warning through one tracepoint - // shouldn't suppress it through the others. - // Later, during warning suppression (when calling - // `suppress_and_deduplicate_warnings`), we deduplicate without - // considering tracepoints, such that, if at least one duplicate wasn't - // suppressed, it is raised. + // shouldn't suppress it through the others. Later, during warning + // suppression (when calling `suppress_and_deduplicate_warnings`), we + // deduplicate without considering tracepoints, such that, if at least + // one duplicate wasn't suppressed, it is raised. let hash = crate::utils::hash128(&( &warning.span, &warning.identifier, @@ -308,6 +309,7 @@ impl Sink { } /// Extend from another sink. + /// /// Using `Sink::extend_tracked` is preferable as it avoids a call to this /// function if all arguments are empty, thus avoiding an unnecessary /// tracked call in most cases. @@ -336,10 +338,8 @@ fn check_warning_suppressed( world: &dyn World, identifier: &diag::Identifier, ) -> bool { - let Some(file) = span.id() else { - // Don't suppress detached warnings. - return false; - }; + // Don't suppress detached warnings. + let Some(file) = span.id() else { return false }; // The source must exist if a warning occurred in the file, // or has a tracepoint in the file.