#[inline]
#[must_use]
pub(crate) fn javadoc_block(s: &[u8]) -> bool {
matches!(s, [b'/', b'*', b'*', b, ..] if *b != b'*' && *b != b'/')
}
#[inline]
#[must_use]
pub(crate) fn tsdoc_block(s: &[u8]) -> bool {
matches!(s, [b'/', b'*', b'*', b, ..] if *b != b'/')
}
#[inline]
#[must_use]
fn triple_slash(s: &[u8]) -> bool {
matches!(s, [b'/', b'/', b'/', rest @ ..] if rest.first() != Some(&b'/'))
}
#[inline]
#[must_use]
pub(crate) fn doxygen(s: &[u8]) -> bool {
javadoc_block(s) || s.starts_with(b"/*!") || triple_slash(s) || s.starts_with(b"//!")
}
#[inline]
#[must_use]
pub(crate) fn java_doc(s: &[u8]) -> bool {
kotlin_doc(s) || triple_slash(s)
}
#[inline]
#[must_use]
pub(crate) fn kotlin_doc(s: &[u8]) -> bool {
s.starts_with(b"/**") && s != b"/**/"
}
#[inline]
#[must_use]
pub(crate) fn phpdoc(s: &[u8]) -> bool {
s.starts_with(b"/**") && s.get(3).is_some_and(u8::is_ascii_whitespace)
}
#[inline]
#[must_use]
pub(crate) fn csharp_doc(s: &[u8]) -> bool {
triple_slash(s) || javadoc_block(s)
}
fn jsdoc_line(line: &[u8]) -> &[u8] {
let line = line.trim_ascii_start();
let line = line.strip_prefix(b"*").unwrap_or(line);
line.strip_prefix(b" ").unwrap_or(line)
}
fn jsdoc_lines(s: &[u8]) -> impl Iterator<Item = &[u8]> + Clone {
let body = s.strip_prefix(b"/**").unwrap_or(s);
let body = body.strip_suffix(b"*/").unwrap_or(body);
let start = body.iter().position(|&b| b != b'*').unwrap_or(body.len());
let end = body
.iter()
.rposition(|&b| b != b'*')
.map_or(start, |at| at + 1);
body[start..end].split(|&b| b == b'\n').map(jsdoc_line)
}
fn jsdoc_tag_open(line: &[u8]) -> Option<(&[u8], &[u8])> {
let tag = line.trim_ascii_start().strip_prefix(b"@")?;
let title = tag.iter().take_while(|b| !b.is_ascii_whitespace()).count();
(title > 0).then(|| tag.split_at(title))
}
fn jsdoc_names<'a>(lines: impl IntoIterator<Item = &'a [u8]>) -> bool {
let mut bytes = lines
.into_iter()
.flat_map(|line| line.iter().copied())
.skip_while(u8::is_ascii_whitespace)
.peekable();
if bytes.peek() == Some(&b'{') {
let mut depth = 0_usize;
for b in bytes.by_ref() {
match b {
b'{' => depth += 1,
b'}' => depth -= 1,
_ => {}
}
if depth == 0 {
break;
}
}
}
bytes.any(|b| !b.is_ascii_whitespace())
}
#[must_use]
pub(crate) fn jsdoc_virtual(s: &[u8]) -> bool {
const ALWAYS: [&[u8]; 4] = [b"file", b"fileoverview", b"overview", b"module"];
const NAMING: [&[u8]; 18] = [
b"name",
b"function",
b"func",
b"method",
b"class",
b"constructor",
b"constant",
b"const",
b"member",
b"var",
b"namespace",
b"mixin",
b"interface",
b"event",
b"external",
b"host",
b"typedef",
b"callback",
];
let is = |title: &[u8], names: &[&[u8]]| names.iter().any(|n| title.eq_ignore_ascii_case(n));
let mut lines = jsdoc_lines(s);
while let Some(line) = lines.next() {
let Some((title, text)) = jsdoc_tag_open(line) else {
continue;
};
if is(title, &ALWAYS) {
return true;
}
let rest = lines.clone().take_while(|l| jsdoc_tag_open(l).is_none());
if is(title, &NAMING) && jsdoc_names(std::iter::once(text).chain(rest)) {
return true;
}
}
false
}
#[must_use]
pub(crate) fn tsdoc_module(s: &[u8]) -> bool {
jsdoc_lines(s)
.filter_map(jsdoc_tag_open)
.any(|(title, _)| title == b"module" || title == b"packageDocumentation")
}
#[must_use]
pub(crate) fn go_directive(s: &[u8]) -> bool {
let Some(rest) = s.strip_prefix(b"//") else {
return false;
};
if rest.starts_with(b"line ") || rest.starts_with(b"extern ") || rest.starts_with(b"export ") {
return true;
}
let word = rest
.iter()
.take_while(|b| b.is_ascii_lowercase() || b.is_ascii_digit())
.count();
word > 0
&& rest.get(word) == Some(&b':')
&& rest
.get(word.saturating_add(1))
.is_some_and(|b| b.is_ascii_lowercase() || b.is_ascii_digit())
}
#[must_use]
pub(crate) fn ruby_directive_opener(s: &[u8]) -> bool {
if s.starts_with(b"##") && s.get(2) != Some(&b'#') {
return true;
}
s.strip_prefix(b"#").is_some_and(|rest| {
rest.iter()
.position(|b| *b != b' ' && *b != b'\t')
.is_some_and(|at| rest[at..].starts_with(b"@!"))
})
}
#[must_use]
pub(crate) fn ruby_magic_comment(s: &[u8]) -> bool {
if s.starts_with(b"#!") {
return true;
}
s.strip_prefix(b"#")
.map(<[u8]>::trim_ascii)
.is_some_and(|body| ruby_modeline(body) || ruby_magic_setting(body))
}
fn contains_ci(hay: &[u8], needle: &[u8]) -> bool {
hay.windows(needle.len())
.any(|window| window.eq_ignore_ascii_case(needle))
}
fn ruby_modeline(body: &[u8]) -> bool {
if body.len() >= 6 && body.starts_with(b"-*-") && body.ends_with(b"-*-") {
return contains_ci(body, b"coding") || contains_ci(body, b"frozen");
}
body.get(..4)
.is_some_and(|head| head.eq_ignore_ascii_case(b"vim:"))
&& contains_ci(body, b"coding")
}
fn ruby_magic_setting(body: &[u8]) -> bool {
let Some(separator) = body.iter().position(|b| matches!(b, b':' | b'=')) else {
return false;
};
let (key, value) = body.split_at(separator);
let value = value.get(1..).unwrap_or_default().trim_ascii_start();
[
&b"coding"[..],
b"encoding",
b"frozen_string_literal",
b"frozen-string-literal",
]
.iter()
.any(|known| key.trim_ascii_end().eq_ignore_ascii_case(known))
&& !value.is_empty()
&& value
.iter()
.all(|b| b.is_ascii_alphanumeric() || matches!(b, b'-' | b'_' | b'.'))
}
#[must_use]
pub(crate) fn pod_comment_region(s: &[u8]) -> bool {
enum Region {
Outside,
Paragraph,
Begin,
}
let mut region = Region::Outside;
let mut regions = 0_usize;
for line in s.split(|&byte| byte == b'\n') {
let blank = line.trim_ascii().is_empty();
match region {
Region::Paragraph if blank => region = Region::Outside,
Region::Begin if pod_command(line, b"=end").is_some_and(is_comment_format) => {
region = Region::Outside;
}
Region::Paragraph | Region::Begin => {}
Region::Outside if blank => {}
Region::Outside => {
if pod_command(line, b"=for").is_some_and(is_comment_format) {
region = Region::Paragraph;
} else if pod_command(line, b"=begin").is_some_and(is_comment_format) {
region = Region::Begin;
} else {
return regions > 0 && line.starts_with(b"=cut");
}
regions += 1;
}
}
}
regions > 0
}
fn pod_command<'s>(line: &'s [u8], command: &[u8]) -> Option<&'s [u8]> {
let rest = line.strip_prefix(command)?;
rest.first()
.is_some_and(u8::is_ascii_whitespace)
.then(|| rest.trim_ascii_start())
}
fn is_comment_format(format: &[u8]) -> bool {
format
.strip_prefix(b"comment")
.is_some_and(|after| after.first().is_none_or(u8::is_ascii_whitespace))
}
#[must_use]
pub(crate) fn ldoc_opener(s: &[u8]) -> bool {
if let Some(body) = lua_long_comment_body(s) {
return body.first() == Some(&b'-');
}
s.starts_with(b"---") && !ldoc_end_marker(s)
}
#[must_use]
pub(crate) fn lua_long_comment(s: &[u8]) -> bool {
lua_long_comment_body(s).is_some()
}
fn lua_long_comment_body(s: &[u8]) -> Option<&[u8]> {
let rest = s.strip_prefix(b"--[")?;
let levels = rest.iter().take_while(|b| **b == b'=').count();
rest.get(levels..)?.strip_prefix(b"[")
}
fn ldoc_end_marker(s: &[u8]) -> bool {
let trimmed = s.len() - s.iter().rev().take_while(|b| **b != b'-').count();
let dashes = s[..trimmed]
.iter()
.rev()
.take_while(|b| **b == b'-')
.count();
dashes >= 2 && trimmed > dashes
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn ruby_directive_opener_accepts_rdoc_and_yard_forms() {
assert!(ruby_directive_opener(b"##"));
assert!(ruby_directive_opener(b"## Section"));
assert!(ruby_directive_opener(b"# @!method foo"));
assert!(ruby_directive_opener(b"#\t@!macro bar"));
assert!(!ruby_directive_opener(b"# plain"));
assert!(!ruby_directive_opener(b"# @param x"));
assert!(!ruby_directive_opener(b"#!/usr/bin/env ruby"));
assert!(!ruby_directive_opener(b"###"));
assert!(!ruby_directive_opener(b"########################"));
assert!(!ruby_directive_opener(b"##### Private helpers #####"));
}
#[test]
fn javadoc_block_accepts_the_block_form_only() {
assert!(javadoc_block(b"/** doc */"));
assert!(javadoc_block(b"/**\n * doc\n */"));
assert!(!javadoc_block(b"/**/"), "empty block");
assert!(!javadoc_block(b"/*** banner */"), "three stars");
assert!(!javadoc_block(b"/* plain */"));
assert!(!javadoc_block(b"// plain"));
assert!(!javadoc_block(b"/**"), "nothing after the marker");
}
#[test]
fn triple_slash_rejects_a_fourth_slash() {
assert!(triple_slash(b"/// doc"));
assert!(triple_slash(b"///"), "bare marker still opens a doc line");
assert!(triple_slash(b"///< after member"));
assert!(!triple_slash(b"//// banner"));
assert!(!triple_slash(b"// plain"));
}
#[test]
fn doxygen_covers_the_four_markers_and_their_member_forms() {
for doc in [
&b"/** d */"[..],
b"/*! d */",
b"/// d",
b"//! d",
b"/**< d */",
b"/*!< d */",
b"///< d",
b"//!< d",
] {
assert!(doxygen(doc), "{}", String::from_utf8_lossy(doc));
}
for plain in [&b"/* d */"[..], b"// d", b"/**/", b"/*** d */", b"//// d"] {
assert!(!doxygen(plain), "{}", String::from_utf8_lossy(plain));
}
}
#[test]
fn java_doc_follows_javac_on_three_stars_and_jep_467() {
assert!(java_doc(b"/** d */"));
assert!(java_doc(b"/*** d */"), "javac discards leading asterisks");
assert!(java_doc(b"/// d"), "JEP 467 Markdown doc comment");
assert!(!java_doc(b"/**/"));
assert!(!java_doc(b"//// d"));
assert!(!java_doc(b"/* d */"));
assert!(!java_doc(b"// d"));
}
#[test]
fn kotlin_doc_is_any_block_but_the_empty_one() {
assert!(kotlin_doc(b"/** d */"));
assert!(kotlin_doc(b"/*** d */"));
assert!(!kotlin_doc(b"/**/"));
assert!(!kotlin_doc(b"/// d"), "KDoc has no line form");
}
#[test]
fn phpdoc_needs_whitespace_after_the_marker() {
assert!(phpdoc(b"/** d */"));
assert!(phpdoc(b"/**\n * d\n */"));
assert!(!phpdoc(b"/**/"));
assert!(!phpdoc(b"/*** d */"));
assert!(!phpdoc(b"/**d */"));
assert!(!phpdoc(b"# d"));
assert!(!phpdoc(b"// d"));
}
#[test]
fn csharp_doc_rejects_the_doxygen_only_spellings() {
assert!(csharp_doc(b"/// <summary>d</summary>"));
assert!(csharp_doc(b"/** d */"));
for plain in [
&b"//! d"[..],
b"/*! d */",
b"//// d",
b"/**/",
b"/*** d */",
b"// d",
] {
assert!(!csharp_doc(plain), "{}", String::from_utf8_lossy(plain));
}
}
#[test]
fn jsdoc_virtual_follows_jsdoc_naming_tags() {
crate::test_support::assert_classifies(
jsdoc_virtual,
&[
b"/** @file */",
b"/**\n * @fileoverview x\n */",
b"/** @overview */",
b"/** @module */",
b"/**\n * @typedef {Object} T\n */",
b"/**\n * @typedef {Object}\n * T\n */",
b"/**\n * @function f\n */",
b"/**\n * @callback cb\n */",
b"/** @FILE */",
b"/** @FileOverview */",
b"/** @Typedef {Object} T */",
b"/** @function f **/",
],
&[
b"/**\n * @license MIT\n */",
b"/**\n * @typedef {Object}\n */",
b"/**\n * @function\n */",
b"/** @function **/",
b"/**\n * @typedef {{a: number}}\n */",
b"/** x @file */",
b"/** d */",
],
);
assert!(tsdoc_module(b"/**\n * @packageDocumentation\n */"));
assert!(tsdoc_module(b"/**\n * @module m\n */"));
assert!(!tsdoc_module(b"/**\n * @license MIT\n */"));
}
#[test]
fn go_directive_matches_go_ast_is_directive() {
for directive in [
&b"//go:build linux"[..],
b"//go:generate go run x",
b"//line foo.go:12",
b"//extern f",
b"//export F",
b"//nolint:errcheck",
b"//x:1",
] {
assert!(
go_directive(directive),
"{}",
String::from_utf8_lossy(directive)
);
}
for text in [
&b"// go:build linux"[..],
b"//Note: not a directive",
b"//x:",
b"//exported F",
b"// d",
] {
assert!(!go_directive(text), "{}", String::from_utf8_lossy(text));
}
}
#[test]
fn pod_comment_region_is_the_comment_format_only() {
for region in [
&b"=begin comment\n\nold();\n\n=end comment\n\n=cut"[..],
b"=for comment\nold();\n\n=cut",
b"=begin comment\n=end comment\n=cut",
b"=for comment\nold();\n",
b"=begin comment\nold();\n",
b"=for comment a\n\n=for comment b\n\n=cut",
b"=begin comment\nx\n=end comment\n=for comment y\n\n=cut",
b"=for comment\r\nold();\r\n\r\n=cut\r\n",
] {
assert!(
pod_comment_region(region),
"{}",
String::from_utf8_lossy(region)
);
}
for doc in [
&b"=pod\n\nText.\n\n=cut"[..],
b"=head1 NAME\n\nFoo\n\n=cut",
b"=begin html\n\n<p>x</p>\n\n=end html\n\n=cut",
b"=begin comments\n=end comments\n=cut",
b"=beginning",
b"=for comment\nInternal note.\n\n=head1 NAME\n\nFoo - bar\n\n=cut",
b"=begin comment\n\nold();\n\n=end comment\n\n=head1 X\n\nDoc.\n\n=cut",
b"=for comment\nnote\n\nPlain text paragraph.\n\n=cut",
] {
assert!(!pod_comment_region(doc), "{}", String::from_utf8_lossy(doc));
}
}
#[test]
fn ruby_magic_comment_matches_whole_magic_lines_only() {
for magic in [
&b"#!/usr/bin/env ruby"[..],
b"# coding: utf-8",
b"# encoding: UTF-8",
b"# Encoding: binary",
b"#coding=utf-8",
b"# -*- coding: utf-8 -*-",
b"# -*- mode: ruby; encoding: utf-8 -*-",
b"# -*- frozen_string_literal: true -*-",
b"# vim: set fileencoding=utf-8 :",
b"# frozen_string_literal: true",
b"# frozen-string-literal: false",
] {
assert!(
ruby_magic_comment(magic),
"{}",
String::from_utf8_lossy(magic)
);
}
for doc in [
&b"# Encoding: defaults to UTF-8."[..],
b"# Handles transcoding: see below",
b"# Pass `frozen_string_literal: true` to opt in.",
b"# Sets the encoding= attribute",
b"# d",
b"#",
] {
assert!(!ruby_magic_comment(doc), "{}", String::from_utf8_lossy(doc));
}
}
}