Prune commentary and stale Rust port notes

app-rust/src/client/highlight/mod.rs

@@ -1,24 +1,3 @@
-//! `code` read once, left to right, into the spans that carry a colour.
-//! Ported from `app/.../Highlighter.kt`.
-//!
-//! One pass with a small state -- in a comment, in a string, or in ordinary
-//! code -- rather than a locator per token kind over the whole text, which
-//! is what the library this replaced did and is why it found comments
-//! before it knew the language: a `#` inside a shell string, a `//` inside
-//! a URL and a block-comment opener inside a shell glob each commented out
-//! the rest of a line that was nothing of the sort.
-//!
-//! Every span is produced by advancing an index forward, so the result is
-//! ordered, non-overlapping and inside the code by construction. Nothing
-//! here panics: an unterminated string or comment runs to the end of the
-//! code, which is also what it looks like while a fence is still being
-//! written.
-//!
-//! **Indices are char offsets, not byte offsets** -- the scanner works over
-//! `Vec<char>`, mirroring the Kotlin original's `Char`-indexed strings, so
-//! [`span_text`] is how a caller (and every test here) turns a [`Span`]
-//! back into the text it covers.
-
 pub mod languages;
 pub mod markdown;
 
@@ -26,7 +5,6 @@ pub use languages::{
     Attributes, BlockComment, Language, Quote, Rules, fence_language, file_language, rules_for,
 };
 
-/// What a span of code is, in the terms a palette has a colour for.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub enum Kind {
     Keyword,
@@ -38,7 +16,6 @@ pub enum Kind {
     Mark,
 }
 
-/// A run of [`Kind`] in the code, as a half-open range of **char** indices.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub struct Span {
     pub start: usize,
@@ -70,8 +47,6 @@ pub fn scan(code: &str, rules: &Rules) -> Vec<Span> {
     Scanner::new(code, rules).run()
 }
 
-/// Characters coloured as punctuation, and as marks. Both sets are the ones
-/// the library this replaced used.
 const PUNCTUATION: &str = ",.:;";
 const MARKS: &str = "()={}<>-+[]|&";
 
@@ -94,8 +69,6 @@ impl<'a> Scanner<'a> {
 
     fn run(mut self) -> Vec<Span> {
         while self.at < self.code.len() {
-            // Every branch that answers true has advanced `self.at`, so
-            // this terminates.
             let consumed = self.block_comment()
                 || self.line_comment()
                 || self.raw_string()
@@ -126,15 +99,12 @@ impl<'a> Scanner<'a> {
         starts_with_at(&self.code, self.at, token)
     }
 
-    /// Whether a line comment token here opens one; see
-    /// [`Rules::line_comments_at_word_start`].
     fn at_word_start(&self) -> bool {
         self.at == 0
             || self.code[self.at - 1].is_whitespace()
             || ";|&(".contains(self.code[self.at - 1])
     }
 
-    /// Whether only whitespace stands between the start of this line and here.
     fn at_line_start(&self) -> bool {
         let mut back = self.at as isize - 1;
         while back >= 0 && self.code[back as usize] != '\n' {
@@ -152,8 +122,6 @@ impl<'a> Scanner<'a> {
         }
     }
 
-    /// From an open bracket through the one that matches it, or to the end
-    /// if none does.
     fn advance_to_matching_bracket(&mut self) {
         let mut depth = 0i32;
         while self.at < self.code.len() {
@@ -180,9 +148,6 @@ impl<'a> Scanner<'a> {
         self.at += comment.open.chars().count();
         let mut depth = 1i32;
         while self.at < self.code.len() && depth > 0 {
-            // The closer is tried first so that a language whose two
-            // delimiters are the same string -- CoffeeScript's `###` --
-            // closes rather than nesting forever.
             if self.starts(comment.close) {
                 depth -= 1;
                 self.at += comment.close.chars().count();
@@ -210,7 +175,6 @@ impl<'a> Scanner<'a> {
         true
     }
 
-    /// Rust and RON: `b`? `r` `#`* `"` ... `"` `#`*, with no escapes inside.
     fn raw_string(&mut self) -> bool {
         if !self.rules.raw_strings {
             return false;
@@ -267,8 +231,6 @@ impl<'a> Scanner<'a> {
     }
 
     fn string(&mut self) -> bool {
-        // Longest opener wins, so Kotlin's `"""` is one delimiter rather
-        // than an empty string followed by a quote.
         let mut quote: Option<Quote> = None;
         for candidate in &self.rules.quotes {
             let current_len = quote.map(|q| q.open.chars().count()).unwrap_or(0);
@@ -346,9 +308,6 @@ impl<'a> Scanner<'a> {
         true
     }
 
-    /// A number is a run starting with a digit and carrying on through
-    /// letters, digits, `_` and `.` -- which covers `0xFF`, `1_000`, `1u32`
-    /// and `3.14` without a grammar for any of them.
     fn number(&mut self) -> bool {
         if !self.code[self.at].is_ascii_digit() {
             return false;
@@ -403,7 +362,6 @@ fn is_word_part(c: char) -> bool {
     c.is_alphanumeric() || c == '_'
 }
 
-/// Whether `code[at..]` starts with `token`, both read as chars.
 fn starts_with_at(code: &[char], at: usize, token: &str) -> bool {
     let token: Vec<char> = token.chars().collect();
     if at + token.len() > code.len() {
@@ -412,8 +370,6 @@ fn starts_with_at(code: &[char], at: usize, token: &str) -> bool {
     code[at..at + token.len()] == token[..]
 }
 
-/// The first index at or after `from` where `code` contains `needle`, or
-/// `None`.
 fn find_from(code: &[char], from: usize, needle: &[char]) -> Option<usize> {
     if needle.is_empty() || from > code.len() {
         return None;
@@ -640,10 +596,6 @@ mod tests {
         }
     }
 
-    /// The scanner must never panic and must never answer a span the code
-    /// does not contain: the library this replaced answered a reversed
-    /// range here, which crashed a card, and a fence still being written is
-    /// an unterminated string or comment on every keystroke.
     #[test]
     fn spans_stay_inside_the_code_for_every_language_and_every_nasty_input() {
         let nasty = [