improve comments and formatting

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.
+    /// The decorator's arguments. Currently, they are always strings.
-    /// Currently, they are always strings.
     pub fn arguments(self) -> impl DoubleEndedIterator<Item = Str<'a>> {
         self.0.children().filter_map(Str::from_untyped)
     }

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
+    /// Note the token could be a [trivia](SyntaxKind::is_trivia). Also, the
-    /// actually come with a subtree (could be an inner node). This happens
+    /// syntax node returned might not always be a leaf, but could actually
-    /// when it is preferred to perform parsing at the character level instead
+    /// come with a subtree (could be an inner node). This happens when it is
-    /// of at the token level, as seen, for example, in
+    /// preferred to perform parsing at the character level instead of at the
-    /// [`decorator`](Lexer::decorator).
+    /// 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<EcoString>, 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.
+    /// Converts a token into a syntax node based on its kind. Produces an
-    /// The node's text is taken from the given start position up to and
+    /// 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
+        // Decorator arguments:
-        // Keep reading until we find a right parenthesis or newline.
+        // Keep reading until we find a right parenthesis or newline. We have
-        // We have to check the newline before eating (through '.peek()') to
+        // to check the newline before eating (through '.peek()') to ensure it
-        // ensure it is not considered part of the decorator.
+        // 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.
+    /// identifiers. Currently, `allow` is the only valid decorator name.
-    /// 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.
+/// Count newlines in text. Only counts up to 2 newlines.
-/// 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);

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),*)))*
     };

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<F, M, T>(
@@ -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.
+                // Can't suppress without an identifier. Therefore, retain the
-                // Therefore, retain the warning.
+                // warning. It is not a duplicate due to the check above.
-                // 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.
+        // shouldn't suppress it through the others. Later, during warning
-        // Later, during warning suppression (when calling
+        // suppression (when calling `suppress_and_deduplicate_warnings`), we
-        // `suppress_and_deduplicate_warnings`), we deduplicate without
+        // deduplicate without considering tracepoints, such that, if at least
-        // considering tracepoints, such that, if at least one duplicate wasn't
+        // one duplicate wasn't suppressed, it is raised.
-        // 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;
+    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.