use crate::language::{SHOULD_PANIC, is_source, text};
use crate::protocol::{DocProse, Example, SourceText};
use syn::spanned::Spanned;
use syn::{Attribute, Expr, ImplItem, Item, Lit, Meta, TraitItem};
pub const RUST_WORDS: [&str; 7] =
["rust", "no_run", SHOULD_PANIC, "edition2015", "edition2018", "edition2021", "edition2024"];
pub struct DocComment {
pub owner: Option<String>,
pub lines: Vec<(usize, String)>,
}
pub fn named(item: &Item) -> Option<(String, &[Attribute])> {
Some(match item {
Item::Const(i) => (i.ident.to_string(), &i.attrs[..]),
Item::Static(i) => (i.ident.to_string(), &i.attrs[..]),
Item::Fn(i) => (i.sig.ident.to_string(), &i.attrs[..]),
Item::Mod(i) => (i.ident.to_string(), &i.attrs[..]),
Item::Macro(i) => (i.ident.as_ref()?.to_string(), &i.attrs[..]),
other => return named_type(other),
})
}
fn named_type(item: &Item) -> Option<(String, &[Attribute])> {
Some(match item {
Item::Struct(i) => (i.ident.to_string(), &i.attrs[..]),
Item::Enum(i) => (i.ident.to_string(), &i.attrs[..]),
Item::Union(i) => (i.ident.to_string(), &i.attrs[..]),
Item::Trait(i) => (i.ident.to_string(), &i.attrs[..]),
Item::Type(i) => (i.ident.to_string(), &i.attrs[..]),
_ => return None,
})
}
pub fn impl_owner(item: &syn::ItemImpl) -> Option<String> {
match &*item.self_ty {
syn::Type::Path(path) => path.path.segments.last().map(|s| s.ident.to_string()),
_ => None,
}
}
fn doc_lines(attrs: &[Attribute]) -> Vec<(usize, String)> {
let mut lines = Vec::new();
for attr in attrs {
let Meta::NameValue(meta) = &attr.meta else { continue };
let Expr::Lit(value) = &meta.value else { continue };
let Lit::Str(written) = &value.lit else { continue };
if !attr.path().is_ident("doc") {
continue;
}
let first = attr.span().start().line;
for (k, line) in written.value().split('\n').enumerate() {
lines.push((first + k, line.strip_prefix(' ').unwrap_or(line).to_string()));
}
}
lines
}
pub fn doc_comments(file: &syn::File) -> Vec<DocComment> {
fn add(out: &mut Vec<DocComment>, owner: Option<String>, attrs: &[Attribute]) {
let lines = doc_lines(attrs);
if !lines.is_empty() {
out.push(DocComment { owner, lines });
}
}
fn walk(items: &[Item], out: &mut Vec<DocComment>) {
for item in items {
if let Some((name, attrs)) = named(item) {
add(out, Some(name), attrs);
}
match item {
Item::Mod(module) => walk(module.content.as_ref().map(|c| &c.1[..]).unwrap_or(&[]), out),
Item::Impl(block) => block.items.iter().for_each(|inner| match inner {
ImplItem::Fn(f) => add(out, impl_owner(block), &f.attrs),
ImplItem::Const(c) => add(out, impl_owner(block), &c.attrs),
_ => {}
}),
Item::Trait(t) => t.items.iter().for_each(|inner| {
if let TraitItem::Fn(f) = inner {
add(out, Some(t.ident.to_string()), &f.attrs);
}
}),
_ => {}
}
}
}
let mut out = Vec::new();
add(&mut out, None, &file.attrs);
walk(&file.items, &mut out);
out
}
fn normalise(prose: &str) -> String {
let mut text = String::new();
let mut rest = prose;
while let Some(start) = rest.find("<!--") {
text.push_str(&rest[..start]);
text.push(' ');
rest = rest[start..].find("-->").map_or("", |end| &rest[start + end + 3..]);
}
text.push_str(rest);
text.split_whitespace().collect::<Vec<_>>().join(" ")
}
struct Fenced {
line: usize,
info: String,
code: String,
}
fn split(comment: &DocComment) -> (String, Vec<Fenced>) {
let (mut prose, mut blocks, mut open) = (String::new(), Vec::new(), None::<Fenced>);
for (line, text) in &comment.lines {
let fence = text.trim_start().strip_prefix("```");
match (&mut open, fence) {
(Some(_), Some(_)) => blocks.extend(open.take()),
(Some(block), None) => block.code = format!("{}{text}\n", block.code),
(None, Some(info)) => {
open = Some(Fenced { line: *line, info: info.trim().to_string(), code: String::new() })
}
(None, None) => prose = format!("{prose}{text}\n"),
}
}
(normalise(&prose), blocks)
}
fn parse(source: &SourceText) -> Option<syn::File> {
is_source(&source.page).then(|| syn::parse_file(&source.text).ok()).flatten()
}
pub fn prose(source: &SourceText) -> Vec<DocProse> {
let Some(file) = parse(source) else { return Vec::new() };
doc_comments(&file)
.iter()
.map(|comment| DocProse {
text: split(comment).0,
start: comment.lines[0].0,
end: comment.lines[comment.lines.len() - 1].0,
})
.collect()
}
fn rust_words(info: &str) -> Option<Vec<&str>> {
let words: Vec<&str> = info.split([',', ' ']).filter(|w| !w.is_empty()).collect();
words.iter().all(|w| RUST_WORDS.contains(w)).then_some(words)
}
pub fn examples(source: &SourceText) -> Vec<Example> {
let Some(file) = parse(source) else { return Vec::new() };
let mut out = Vec::new();
for comment in doc_comments(&file) {
let (claim, blocks) = split(&comment);
for block in blocks {
let Some(words) = rust_words(&block.info) else { continue };
let panics = words.contains(&SHOULD_PANIC);
let runs = !words.contains(&"no_run");
out.push(Example {
id: format!("{}#L{}", source.page, block.line),
page: source.page.clone(),
line: block.line,
claim: claim.clone(),
kind: "example".into(),
lang: "rust".into(),
mode: if runs { "check" } else { "compile" }.into(),
weak: runs && !panics && !text::asserts(&block.code),
code: block.code,
owner: comment.owner.clone(),
tags: if panics { vec![SHOULD_PANIC.into()] } else { Vec::new() },
..Example::default()
});
}
}
out
}
#[cfg(test)]
mod tests {
use super::*;
const SOURCE: &str = r#"//! A small crate.
/// Adds two numbers, <!-- a note --> whatever
/// their order.
///
/// ```
/// assert_eq!(kit::add(1, 2), 3);
/// ```
///
/// It never panics.
///
/// ```should_panic
/// kit::add(1, 2);
/// ```
pub fn add(a: i64, b: i64) -> i64 {
a + b
}
pub struct Money;
impl Money {
/// An amount.
///
/// ```rust,no_run
/// let m = kit::Money::new();
/// ```
///
/// ```sh
/// cargo run
/// ```
///
/// ```ignore
/// nothing
/// ```
pub fn new() -> Money {
Money
}
}
"#;
fn source(page: &str) -> SourceText {
SourceText { page: page.into(), text: SOURCE.into() }
}
#[test]
fn examples_are_the_rust_blocks_of_doc_comments() {
let found = examples(&source("src/lib.rs"));
let read: Vec<_> = found
.iter()
.map(|e| (e.line, e.mode.as_str(), e.owner.as_deref(), e.weak, e.tags.len()))
.collect();
assert_eq!(
read,
[
(6, "check", Some("add"), false, 0),
(12, "check", Some("add"), false, 1),
(24, "compile", Some("Money"), false, 0)
]
);
assert_eq!(found[0].claim, "Adds two numbers, whatever their order. It never panics.");
assert_eq!(found[0].code, "assert_eq!(kit::add(1, 2), 3);\n");
assert_eq!(found[0].id, "src/lib.rs#L6");
assert!(examples(&source("docs/notes.txt")).is_empty());
}
#[test]
fn prose_is_each_doc_comment_without_its_blocks() {
let found = prose(&source("src/lib.rs"));
let want = [
("A small crate.", 1, 1),
("Adds two numbers, whatever their order. It never panics.", 3, 14),
("An amount.", 22, 34),
];
let read: Vec<_> = found.iter().map(|p| (p.text.as_str(), p.start, p.end)).collect();
assert_eq!(read, want);
assert!(prose(&source("docs/notes.txt")).is_empty());
}
}