docs: correct stale style and HTML formatter doc comments

alecthomas · claude · alecthomas · commit d5de02606901 · 2026-07-08T12:06:37.000+10:00
synthesise's line-number comment described values the code never
used; WithCSSComments' description was wrong; HighlightLines and
WithLinePrompts did not mention that ranges follow BaseLineNumber.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/formatters/html/html.go b/formatters/html/html.go
@@ -37,7 +37,8 @@ func WithCustomCSS(css map[chroma.TokenType]string) Option {
 	}
 }
 
-// WithCSSComments adds prefixe comments to the css classes. Defaults to true.
+// WithCSSComments prefixes each generated CSS rule with a comment naming its
+// token type. Defaults to true.
 func WithCSSComments(b bool) Option { return func(f *Formatter) { f.writeCSSComments = b } }
 
 // TabWidth sets the number of characters for a tab. Defaults to 8.
@@ -122,9 +123,11 @@ func WithLinkableLineNumbers(b bool, prefix string) Option {
 	}
 }
 
-// HighlightLines higlights the given line ranges with the Highlight style.
+// HighlightLines highlights the given line ranges with the Highlight style.
 //
-// A range is the beginning and ending of a range as 1-based line numbers, inclusive.
+// A range is the beginning and ending of a range as 1-based line numbers,
+// inclusive. Ranges are matched against displayed line numbers, so they
+// follow BaseLineNumber.
 func HighlightLines(ranges [][2]int) Option {
 	return func(f *Formatter) {
 		f.highlightRanges = ranges
@@ -134,7 +137,9 @@ func HighlightLines(ranges [][2]int) Option {
 
 // WithLinePrompts adds a non-selectable prompt before each line in the given ranges.
 //
-// A range is the beginning and ending of a range as 1-based line numbers, inclusive.
+// A range is the beginning and ending of a range as 1-based line numbers,
+// inclusive. Ranges are matched against displayed line numbers, so they
+// follow BaseLineNumber.
 func WithLinePrompts(prompt string, ranges [][2]int) Option {
 	return func(f *Formatter) {
 		f.linePrompt = prompt
diff --git a/style.go b/style.go
@@ -462,7 +462,7 @@ func (s *Style) synthesise(ttype TokenType) StyleEntry {
 	case LineHighlight:
 		return StyleEntry{Background: bg.Background.BrightenOrDarken(0.1)}
 
-	// If we don't have line numbers, use the text colour but 20% brighter/darker
+	// If we don't have line numbers, derive a colour from the background, 50% brighter/darker.
 	case LineNumbers, LineNumbersTable:
 		return text
 
