Skip to main content

reflex/parsers/api/
go.rs

1//! Go API extraction by walking the syntax tree.
2//!
3//! Top-level declarations are read in source order. A doc comment is the comment group
4//! (`//` lines or a `/* */` block) that ends on the line right above a declaration;
5//! a blank line breaks the group. Function bodies are never entered.
6//!
7//! Go doc comments (go.dev/doc/comment) are not Markdown, so they are converted:
8//! indented spans become code blocks (or lists, when they start with a list marker),
9//! `# Heading` lines become headings, `[Name]` / `[pkg.Name]` doc links become
10//! intra-doc links (`` [`Name`] ``), and a `Deprecated:` paragraph becomes
11//! [`ApiItem::deprecated`].
12
13use super::{
14    ApiFile, ApiItem, ApiKind, Deprecation, DocComment, Param, SigParts, Visibility, collapse_ws,
15    doc,
16};
17use crate::models::Language;
18use anyhow::{Context, Result};
19use tree_sitter::Node;
20
21/// Longest signature kept, in characters.
22const MAX_SIGNATURE: usize = 600;
23/// Longest `const`/`var` value shown in a signature; longer ones become `…`.
24const MAX_VALUE: usize = 80;
25
26fn parse(source: &str) -> Result<tree_sitter::Tree> {
27    let mut parser = tree_sitter::Parser::new();
28    parser
29        .set_language(&crate::parsers::ParserFactory::get_language_grammar(
30            Language::Go,
31        )?)
32        .context("loading the Go grammar")?;
33    parser.parse(source, None).context("parsing Go")
34}
35
36pub fn extract(source: &str) -> Result<ApiFile> {
37    let tree = parse(source)?;
38    let root = tree.root_node();
39    let mut file = ApiFile::default();
40    let mut group = CommentGroup::default();
41    let mut prev_end: Option<usize> = None;
42    let mut c = root.walk();
43    for child in root.named_children(&mut c) {
44        if child.kind() == "comment" {
45            // A comment on the line a declaration ends on belongs to that declaration.
46            if prev_end != Some(child.start_position().row) {
47                group.push(&child, source);
48            }
49            continue;
50        }
51        let doc = group.take_for(&child);
52        prev_end = Some(child.end_position().row);
53        match child.kind() {
54            "package_clause" => {
55                let mut pc = child.walk();
56                file.package = child
57                    .named_children(&mut pc)
58                    .find(|n| n.kind() == "package_identifier")
59                    .map(|n| text(&n, source).to_string());
60                file.module_doc = doc.and_then(|d| d.doc);
61            }
62            "function_declaration" | "method_declaration" => {
63                file.items.push(function(&child, source, doc));
64            }
65            "type_declaration" => type_decl(&child, source, doc, &mut file.items),
66            "const_declaration" | "var_declaration" => {
67                value_decl(&child, source, doc, &mut file.items)
68            }
69            _ => {}
70        }
71    }
72    Ok(file)
73}
74
75/// An `Example…` function from a `_test.go` file.
76#[derive(Debug, Clone, PartialEq)]
77pub struct Example {
78    /// The name without the `Example` prefix: `""`, `Foo`, `T_M`, `T_M_suffix`.
79    pub name: String,
80    /// The function body, unindented, including its `// Output:` comment.
81    pub code: String,
82    pub doc: Option<String>,
83}
84
85/// `Example…` functions of a test file (testable examples, go.dev/blog/examples).
86pub fn examples(source: &str) -> Result<Vec<Example>> {
87    let tree = parse(source)?;
88    let root = tree.root_node();
89    let mut out = Vec::new();
90    let mut group = CommentGroup::default();
91    let mut c = root.walk();
92    for child in root.named_children(&mut c) {
93        if child.kind() == "comment" {
94            group.push(&child, source);
95            continue;
96        }
97        let doc = group.take_for(&child);
98        if child.kind() != "function_declaration" {
99            continue;
100        }
101        let name = child
102            .child_by_field_name("name")
103            .map(|n| text(&n, source))
104            .unwrap_or("");
105        let Some(rest) = name.strip_prefix("Example") else {
106            continue;
107        };
108        // `Examplefoo` is not an example; `Example_suffix` is the package example.
109        if rest.starts_with(|c: char| c.is_lowercase()) {
110            continue;
111        }
112        let no_params = child
113            .child_by_field_name("parameters")
114            .is_some_and(|p| p.named_child_count() == 0);
115        let Some(body) = child.child_by_field_name("body") else {
116            continue;
117        };
118        if !no_params || child.child_by_field_name("result").is_some() {
119            continue;
120        }
121        let inner = text(&body, source);
122        let inner = inner
123            .strip_prefix('{')
124            .and_then(|s| s.strip_suffix('}'))
125            .unwrap_or(inner);
126        let lines: Vec<String> = inner.lines().map(|l| l.trim_end().to_string()).collect();
127        let code = unindent(trim_blank(lines)).join("\n");
128        out.push(Example {
129            name: rest.to_string(),
130            code,
131            doc: doc.and_then(|d| d.doc).map(|d| d.markdown),
132        });
133    }
134    Ok(out)
135}
136
137fn text<'s>(node: &Node, src: &'s str) -> &'s str {
138    node.utf8_text(src.as_bytes()).unwrap_or("")
139}
140
141fn line(node: &Node) -> u32 {
142    node.start_position().row as u32 + 1
143}
144
145fn end_line(node: &Node) -> u32 {
146    node.end_position().row as u32 + 1
147}
148
149/// Exported names start with an uppercase letter.
150pub fn is_exported(name: &str) -> bool {
151    name.chars().next().is_some_and(char::is_uppercase)
152}
153
154fn visibility(name: &str) -> Visibility {
155    if is_exported(name) {
156        Visibility::Public
157    } else {
158        Visibility::Private
159    }
160}
161
162/// Consecutive comments, reset by a blank line.
163#[derive(Default)]
164struct CommentGroup {
165    /// (start row, end row, text lines).
166    comments: Vec<(usize, usize, Vec<String>)>,
167}
168
169/// A converted doc comment and the deprecation notice found in it.
170#[derive(Default)]
171struct Doc {
172    doc: Option<DocComment>,
173    deprecated: Option<Deprecation>,
174}
175
176impl CommentGroup {
177    fn push(&mut self, node: &Node, src: &str) {
178        let (start, end) = (node.start_position().row, node.end_position().row);
179        if let Some(&(_, last_end, _)) = self.comments.last()
180            && start > last_end + 1
181        {
182            self.comments.clear();
183        }
184        self.comments.push((start, end, comment_lines(node, src)));
185    }
186
187    /// The group, as the doc of `node`, if it ends on the line right above it.
188    fn take_for(&mut self, node: &Node) -> Option<Doc> {
189        let comments = std::mem::take(&mut self.comments);
190        let &(_, last_end, _) = comments.last()?;
191        let row = node.start_position().row;
192        if last_end + 1 != row && last_end != row {
193            return None;
194        }
195        let start = comments[0].0;
196        let lines: Vec<String> = comments.into_iter().flat_map(|(_, _, l)| l).collect();
197        Some(convert(&lines, start as u32 + 1, last_end as u32 + 1))
198    }
199}
200
201/// The text of one comment with its markers removed; directives are dropped.
202fn comment_lines(node: &Node, src: &str) -> Vec<String> {
203    let t = text(node, src);
204    if let Some(rest) = t.strip_prefix("//") {
205        if is_directive(rest) {
206            return Vec::new();
207        }
208        return vec![
209            rest.strip_prefix(' ')
210                .unwrap_or(rest)
211                .trim_end()
212                .to_string(),
213        ];
214    }
215    let inner = t
216        .strip_prefix("/*")
217        .and_then(|s| s.strip_suffix("*/"))
218        .unwrap_or(t);
219    let mut lines: Vec<String> = inner.lines().map(|l| l.trim_end().to_string()).collect();
220    if let Some(first) = lines.first_mut() {
221        *first = first.trim_start().to_string();
222    }
223    strip_block_stars(&mut lines);
224    lines
225}
226
227/// `/*\n * a\n * b\n */` → `a`, `b`.
228fn strip_block_stars(lines: &mut [String]) {
229    let nonblank: Vec<&String> = lines.iter().filter(|l| !l.trim().is_empty()).collect();
230    if nonblank.len() > 1 && nonblank.iter().all(|l| l.trim_start().starts_with('*')) {
231        for l in lines.iter_mut() {
232            let t = l.trim_start();
233            *l = t
234                .strip_prefix("* ")
235                .or_else(|| t.strip_prefix('*'))
236                .unwrap_or(t)
237                .to_string();
238        }
239    }
240}
241
242/// `//go:generate`, `//nolint:x`, `//line`, `//export`: not documentation.
243fn is_directive(after_slashes: &str) -> bool {
244    let s = after_slashes;
245    if s.starts_with("line ") || s.starts_with("extern ") || s.starts_with("export ") {
246        return true;
247    }
248    if s.starts_with(" +build") || s.starts_with("+build") {
249        return true;
250    }
251    let word: String = s
252        .chars()
253        .take_while(|c| c.is_ascii_lowercase() || c.is_ascii_digit())
254        .collect();
255    !word.is_empty()
256        && s[word.len()..].starts_with(':')
257        && s[word.len() + 1..]
258            .chars()
259            .next()
260            .is_some_and(|c| c.is_ascii_lowercase() || c.is_ascii_digit())
261}
262
263fn trim_blank(mut lines: Vec<String>) -> Vec<String> {
264    while lines.first().is_some_and(|l| l.trim().is_empty()) {
265        lines.remove(0);
266    }
267    while lines.last().is_some_and(|l| l.trim().is_empty()) {
268        lines.pop();
269    }
270    lines
271}
272
273/// Remove the longest common space/tab prefix of the non-blank lines.
274fn unindent(lines: Vec<String>) -> Vec<String> {
275    let mut prefix: Option<&str> = None;
276    for l in lines.iter().filter(|l| !l.trim().is_empty()) {
277        let ws = &l[..l.len() - l.trim_start_matches([' ', '\t']).len()];
278        prefix = Some(match prefix {
279            None => ws,
280            Some(p) => {
281                let n = p
282                    .bytes()
283                    .zip(ws.bytes())
284                    .take_while(|(a, b)| a == b)
285                    .count();
286                &p[..n]
287            }
288        });
289    }
290    let n = prefix.map(str::len).unwrap_or(0);
291    lines
292        .iter()
293        .map(|l| {
294            if l.trim().is_empty() {
295                String::new()
296            } else {
297                l[n..].to_string()
298            }
299        })
300        .collect()
301}
302
303fn is_indented(line: &str) -> bool {
304    line.starts_with([' ', '\t'])
305}
306
307/// A list marker at the start of `t` (already trimmed): `-`, `*`, `+`, `•`, `1.`, `1)`.
308fn list_marker(t: &str) -> Option<(bool, &str)> {
309    for m in ["- ", "* ", "+ ", "• "] {
310        if let Some(rest) = t.strip_prefix(m) {
311            return Some((false, rest));
312        }
313    }
314    let digits = t.chars().take_while(char::is_ascii_digit).count();
315    if digits > 0 {
316        let rest = &t[digits..];
317        if let Some(r) = rest.strip_prefix(". ").or_else(|| rest.strip_prefix(") ")) {
318            return Some((true, r));
319        }
320    }
321    None
322}
323
324/// Convert Go doc comment lines to a [`Doc`].
325fn convert(raw: &[String], start_line: u32, end_line: u32) -> Doc {
326    let lines = unindent(trim_blank(raw.to_vec()));
327    let mut md: Vec<String> = Vec::new();
328    let mut links: Vec<String> = Vec::new();
329    let mut summary: Option<String> = None;
330    let mut deprecated: Option<Deprecation> = None;
331    let mut i = 0;
332    let blank_before = |md: &mut Vec<String>| {
333        if md.last().is_some_and(|l| !l.is_empty()) {
334            md.push(String::new());
335        }
336    };
337    while i < lines.len() {
338        let l = &lines[i];
339        if l.trim().is_empty() {
340            i += 1;
341            continue;
342        }
343        if is_indented(l) {
344            // A span of indented (or blank) lines: a list or a code block.
345            let mut span = Vec::new();
346            while i < lines.len() && (lines[i].is_empty() || is_indented(&lines[i])) {
347                span.push(lines[i].clone());
348                i += 1;
349            }
350            let span = trim_blank(span);
351            blank_before(&mut md);
352            if list_marker(span[0].trim_start()).is_some() {
353                let mut items: Vec<(bool, String)> = Vec::new();
354                for s in &span {
355                    let t = s.trim();
356                    if t.is_empty() {
357                        continue;
358                    }
359                    match list_marker(t) {
360                        Some((numbered, rest)) => items.push((numbered, rest.to_string())),
361                        None => {
362                            if let Some((_, last)) = items.last_mut() {
363                                last.push(' ');
364                                last.push_str(t);
365                            }
366                        }
367                    }
368                }
369                let mut n = 0;
370                for (numbered, item) in items {
371                    let body = inline(&item, &mut links, true);
372                    if numbered {
373                        n += 1;
374                        md.push(format!("{n}. {body}"));
375                    } else {
376                        md.push(format!("- {body}"));
377                    }
378                }
379            } else {
380                md.push("```go".into());
381                md.extend(unindent(span));
382                md.push("```".into());
383            }
384            md.push(String::new());
385            continue;
386        }
387        // A paragraph: unindented lines up to a blank or indented line.
388        let mut para = Vec::new();
389        while i < lines.len() && !lines[i].trim().is_empty() && !is_indented(&lines[i]) {
390            para.push(lines[i].as_str());
391            i += 1;
392        }
393        if para.len() == 1
394            && let Some(h) = para[0].strip_prefix("# ")
395            && !h.trim().is_empty()
396        {
397            blank_before(&mut md);
398            md.push(format!("# {}", inline(h.trim(), &mut links, true)));
399            md.push(String::new());
400            continue;
401        }
402        if deprecated.is_none()
403            && let Some(rest) = para[0].strip_prefix("Deprecated:")
404        {
405            let mut note = vec![rest.trim()];
406            note.extend(para[1..].iter().map(|l| l.trim()));
407            let note = note.join(" ").trim().to_string();
408            deprecated = Some(Deprecation {
409                since: None,
410                note: (!note.is_empty()).then_some(note),
411            });
412            continue;
413        }
414        if summary.is_none() {
415            let joined = para.join(" ");
416            summary = Some(inline(first_sentence(&joined), &mut Vec::new(), false));
417        }
418        blank_before(&mut md);
419        for p in &para {
420            md.push(escape_line_start(&inline(p, &mut links, true)));
421        }
422        md.push(String::new());
423    }
424    let markdown = md.join("\n").trim_matches('\n').to_string();
425    let doc = (!markdown.trim().is_empty()).then(|| DocComment {
426        summary: summary.unwrap_or_default(),
427        sections: doc::sections(&markdown),
428        examples: doc::examples(&markdown),
429        links,
430        markdown,
431        start_line,
432        end_line,
433    });
434    Doc { doc, deprecated }
435}
436
437/// Go's synopsis rule: the text up to the first period followed by a space that does
438/// not end a single capital letter (`U.S. `), or the whole text.
439fn first_sentence(s: &str) -> &str {
440    let (mut ppp, mut pp, mut p) = (' ', ' ', ' ');
441    for (i, q) in s.char_indices() {
442        let q = if q.is_whitespace() { ' ' } else { q };
443        if q == ' ' && p == '.' && (!pp.is_uppercase() || ppp.is_uppercase()) {
444            return &s[..i];
445        }
446        if p == '。' || p == '.' {
447            return &s[..i];
448        }
449        (ppp, pp, p) = (pp, p, q);
450    }
451    s
452}
453
454/// Keep a paragraph line from turning into a Markdown heading, quote or rule.
455fn escape_line_start(line: &str) -> String {
456    let t = line.trim_start();
457    if t.starts_with('#') || t.starts_with('>') {
458        return format!("\\{t}");
459    }
460    if !t.is_empty() && t.chars().all(|c| c == '=' || c == '-') {
461        return format!("\\{t}");
462    }
463    line.to_string()
464}
465
466/// A Go doc link target: `Name`, `Name.Method`, `pkg.Name`, `pkg.Name.Method`.
467fn doc_link_target(inner: &str) -> bool {
468    let segs: Vec<&str> = inner.split('.').collect();
469    let ident = |s: &str| {
470        s.chars()
471            .next()
472            .is_some_and(|c| c.is_alphabetic() || c == '_')
473            && s.chars().all(|c| c.is_alphanumeric() || c == '_')
474    };
475    if !segs.iter().all(|s| ident(s)) {
476        return false;
477    }
478    match segs.as_slice() {
479        [name] => is_exported(name),
480        [a, b] => is_exported(a) || is_exported(b),
481        [pkg, ty, _] => !is_exported(pkg) && is_exported(ty),
482        _ => false,
483    }
484}
485
486/// Inline text: doc links become `` [`Name`] `` (recorded in `links`) and, when
487/// `escape` is set, Markdown emphasis and HTML characters are escaped outside
488/// backtick code spans.
489fn inline(s: &str, links: &mut Vec<String>, escape: bool) -> String {
490    let chars: Vec<char> = s.chars().collect();
491    let mut out = String::with_capacity(s.len() + 8);
492    let mut in_code = false;
493    let mut i = 0;
494    let word = |c: char| c.is_alphanumeric() || c == '_';
495    while i < chars.len() {
496        let c = chars[i];
497        if c == '`' {
498            // Toggle only when a closing backtick exists.
499            if in_code || chars[i + 1..].contains(&'`') {
500                in_code = !in_code;
501            }
502            out.push(c);
503            i += 1;
504            continue;
505        }
506        if in_code {
507            out.push(c);
508            i += 1;
509            continue;
510        }
511        if c == '['
512            && (i == 0 || !word(chars[i - 1]))
513            && let Some(len) = chars[i + 1..].iter().position(|&c| c == ']')
514        {
515            let inner: String = chars[i + 1..i + 1 + len].iter().collect();
516            let after = chars.get(i + 2 + len).copied();
517            let ok_after = after.is_none_or(|a| !word(a) && a != '(' && a != '[')
518                && !(i == 0 && after == Some(':'));
519            let (star, target) = match inner.strip_prefix('*') {
520                Some(t) => (true, t.to_string()),
521                None => (false, inner.clone()),
522            };
523            if ok_after {
524                if target.contains('/') && doc_link_target(target.rsplit('/').next().unwrap_or(""))
525                {
526                    // An import-path link (`[net/http.Client]`): shown as code.
527                    out.push('`');
528                    out.push_str(&inner);
529                    out.push('`');
530                    i += len + 2;
531                    continue;
532                }
533                if doc_link_target(&target) {
534                    if star {
535                        out.push_str(if escape { "\\*" } else { "*" });
536                    }
537                    out.push_str(&format!("[`{target}`]"));
538                    if !links.contains(&target) {
539                        links.push(target);
540                    }
541                    i += len + 2;
542                    continue;
543                }
544            }
545        }
546        if escape {
547            match c {
548                '*' | '<' => out.push('\\'),
549                '\\' if chars.get(i + 1).is_some_and(|n| n.is_ascii_punctuation()) => {
550                    out.push('\\');
551                }
552                '_' => {
553                    let prev = i.checked_sub(1).map(|p| chars[p]);
554                    let next = chars.get(i + 1).copied();
555                    if !prev.is_some_and(char::is_alphanumeric)
556                        || !next.is_some_and(char::is_alphanumeric)
557                    {
558                        out.push('\\');
559                    }
560                }
561                _ => {}
562            }
563        }
564        out.push(c);
565        i += 1;
566    }
567    out
568}
569
570/// Declaration text from `node` up to `body` (or the whole node), whitespace-collapsed.
571fn signature(node: &Node, src: &str) -> String {
572    let end = node
573        .child_by_field_name("body")
574        .map(|b| b.start_byte())
575        .unwrap_or(node.end_byte());
576    cap(clean_until(node, src, end))
577}
578
579/// `node`'s text, comments removed and whitespace collapsed.
580fn clean(node: &Node, src: &str) -> String {
581    clean_until(node, src, node.end_byte())
582}
583
584/// `node`'s text up to byte `end`, comments removed and whitespace collapsed, so a
585/// parameter list annotated line by line reads as a clean one-line signature. Comments
586/// are found in the tree, so `//` inside a string or struct tag is kept.
587fn clean_until(node: &Node, src: &str, end: usize) -> String {
588    let mut comments = Vec::new();
589    let mut stack = vec![*node];
590    while let Some(n) = stack.pop() {
591        let mut c = n.walk();
592        for ch in n.children(&mut c) {
593            if ch.start_byte() >= end {
594                break;
595            }
596            if ch.kind() == "comment" {
597                comments.push((ch.start_byte(), ch.end_byte().min(end)));
598            } else if ch.child_count() > 0 {
599                stack.push(ch);
600            }
601        }
602    }
603    comments.sort_unstable();
604    let mut out = String::new();
605    let mut pos = node.start_byte();
606    for (a, b) in comments {
607        if a >= pos {
608            out.push_str(&src[pos..a]);
609            out.push(' ');
610            pos = b;
611        }
612    }
613    out.push_str(&src[pos..end.max(pos)]);
614    collapse_ws(out.trim())
615}
616
617fn cap(mut s: String) -> String {
618    if s.chars().count() > MAX_SIGNATURE {
619        s = s.chars().take(MAX_SIGNATURE).collect::<String>() + " …";
620    }
621    s
622}
623
624/// `*List[T]`, `pkg.T`, `T[K, V]` → `List`, `T`, `T`.
625pub fn base_type_name(t: &str) -> &str {
626    let t = t.trim().trim_start_matches('*').trim();
627    let t = t.split('[').next().unwrap_or(t);
628    t.rsplit('.').next().unwrap_or(t).trim()
629}
630
631fn params(list: &Node, src: &str) -> Vec<Param> {
632    let mut out = Vec::new();
633    let mut c = list.walk();
634    for p in list.named_children(&mut c) {
635        let variadic = p.kind() == "variadic_parameter_declaration";
636        if p.kind() != "parameter_declaration" && !variadic {
637            continue;
638        }
639        let mut ty = p
640            .child_by_field_name("type")
641            .map(|n| clean(&n, src))
642            .unwrap_or_default();
643        if variadic {
644            ty = format!("...{ty}");
645        }
646        let mut nc = p.walk();
647        let names: Vec<String> = p
648            .children_by_field_name("name", &mut nc)
649            .filter(|n| n.kind() == "identifier")
650            .map(|n| text(&n, src).to_string())
651            .collect();
652        if names.is_empty() {
653            out.push(Param {
654                name: String::new(),
655                ty,
656            });
657            continue;
658        }
659        for name in names {
660            out.push(Param {
661                name,
662                ty: ty.clone(),
663            });
664        }
665    }
666    out
667}
668
669fn sig_parts(node: &Node, src: &str) -> SigParts {
670    let mut sig = SigParts::default();
671    if let Some(tp) = node.child_by_field_name("type_parameters") {
672        sig.generics = Some(clean(&tp, src));
673    }
674    if let Some(r) = node.child_by_field_name("receiver") {
675        let t = clean(&r, src);
676        sig.receiver = Some(
677            t.trim_start_matches('(')
678                .trim_end_matches(')')
679                .trim()
680                .to_string(),
681        );
682    }
683    if let Some(p) = node.child_by_field_name("parameters") {
684        sig.params = params(&p, src);
685    }
686    if let Some(r) = node.child_by_field_name("result") {
687        sig.returns = Some(clean(&r, src));
688    }
689    sig
690}
691
692fn new_item(name: String, kind: ApiKind, node: &Node, doc: Option<Doc>) -> ApiItem {
693    let doc = doc.unwrap_or_default();
694    ApiItem {
695        visibility: visibility(&name),
696        name,
697        kind,
698        signature: String::new(),
699        sig: None,
700        doc: doc.doc,
701        attrs: Vec::new(),
702        deprecated: doc.deprecated,
703        hidden: false,
704        test_only: false,
705        start_line: line(node),
706        end_line: end_line(node),
707        trait_impl: None,
708        self_type: None,
709        members: Vec::new(),
710    }
711}
712
713fn function(node: &Node, src: &str, doc: Option<Doc>) -> ApiItem {
714    let name = node
715        .child_by_field_name("name")
716        .map(|n| text(&n, src).to_string())
717        .unwrap_or_default();
718    let is_method = node.kind() == "method_declaration";
719    let kind = if is_method {
720        ApiKind::Method
721    } else {
722        ApiKind::Function
723    };
724    let mut it = new_item(name, kind, node, doc);
725    it.signature = signature(node, src);
726    let sig = sig_parts(node, src);
727    if is_method {
728        // The receiver's type: `(c *Client)` → `Client`, `(l *List[T])` → `List`.
729        it.self_type = node.child_by_field_name("receiver").and_then(|r| {
730            let mut c = r.walk();
731            let p = r
732                .named_children(&mut c)
733                .find(|p| p.kind() == "parameter_declaration")?;
734            let ty = p.child_by_field_name("type")?;
735            Some(base_type_name(text(&ty, src)).to_string())
736        });
737    }
738    it.sig = Some(sig);
739    it
740}
741
742/// Whether a `type`/`const`/`var` declaration is parenthesized.
743fn is_grouped(node: &Node) -> bool {
744    let mut c = node.walk();
745    node.children(&mut c)
746        .any(|ch| ch.kind() == "(" || ch.kind() == "var_spec_list")
747}
748
749/// Specs of a declaration, each with its own doc comment (and trailing comment).
750fn specs<'t>(node: &Node<'t>, src: &str, kinds: &[&str]) -> Vec<(Node<'t>, Option<Doc>)> {
751    let mut out: Vec<(Node<'t>, Option<Doc>)> = Vec::new();
752    let mut group = CommentGroup::default();
753    let mut prev_end: Option<usize> = None;
754    let mut stack = vec![*node];
755    while let Some(n) = stack.pop() {
756        let mut c = n.walk();
757        let children: Vec<Node<'t>> = n.named_children(&mut c).collect();
758        for ch in children {
759            if ch.kind() == "var_spec_list" {
760                stack.push(ch);
761                continue;
762            }
763            if ch.kind() == "comment" {
764                if prev_end == Some(ch.start_position().row) {
765                    // Trailing comment: the previous spec's doc when it has none.
766                    if let Some((_, d)) = out.last_mut()
767                        && d.as_ref().is_none_or(|d| d.doc.is_none())
768                    {
769                        let lines = comment_lines(&ch, src);
770                        let deprecated = d.take().and_then(|d| d.deprecated);
771                        let mut converted = convert(&lines, line(&ch), end_line(&ch));
772                        converted.deprecated = converted.deprecated.or(deprecated);
773                        *d = Some(converted);
774                    }
775                } else {
776                    group.push(&ch, src);
777                }
778                continue;
779            }
780            if kinds.contains(&ch.kind()) {
781                let d = group.take_for(&ch);
782                prev_end = Some(ch.end_position().row);
783                out.push((ch, d));
784            }
785        }
786    }
787    out
788}
789
790fn type_decl(node: &Node, src: &str, decl_doc: Option<Doc>, out: &mut Vec<ApiItem>) {
791    let grouped = is_grouped(node);
792    let specs = specs(node, src, &["type_spec", "type_alias"]);
793    let mut decl_doc = decl_doc;
794    for (spec, doc) in &specs {
795        let has_own = doc.as_ref().is_some_and(|d| d.doc.is_some());
796        // Like go/doc, a type without its own doc uses the declaration's.
797        let doc = if has_own || decl_doc.is_none() {
798            doc.as_ref().map(clone_doc)
799        } else if grouped {
800            decl_doc.as_ref().map(clone_doc)
801        } else {
802            decl_doc.take()
803        };
804        let span = if grouped { spec } else { node };
805        out.push(type_spec(spec, span, src, doc));
806    }
807}
808
809fn clone_doc(d: &Doc) -> Doc {
810    Doc {
811        doc: d.doc.clone(),
812        deprecated: d.deprecated.clone(),
813    }
814}
815
816fn type_spec(spec: &Node, span: &Node, src: &str, doc: Option<Doc>) -> ApiItem {
817    let name = spec
818        .child_by_field_name("name")
819        .map(|n| text(&n, src).to_string())
820        .unwrap_or_default();
821    let tparams = spec
822        .child_by_field_name("type_parameters")
823        .map(|t| clean(&t, src));
824    let ty = spec.child_by_field_name("type");
825    let kind = match (spec.kind(), ty.map(|t| t.kind())) {
826        ("type_alias", _) => ApiKind::TypeAlias,
827        (_, Some("struct_type")) => ApiKind::Struct,
828        (_, Some("interface_type")) => ApiKind::Interface,
829        // A defined type (`type Kind int`) documents like an alias; its methods attach
830        // in the surface.
831        _ => ApiKind::TypeAlias,
832    };
833    let mut it = new_item(name.clone(), kind, span, doc);
834    let tp = tparams.clone().unwrap_or_default();
835    it.signature = match kind {
836        ApiKind::Struct => format!("type {name}{tp} struct"),
837        ApiKind::Interface => format!("type {name}{tp} interface"),
838        _ => cap(format!("type {}", clean(spec, src))),
839    };
840    if tparams.is_some() {
841        it.sig = Some(SigParts {
842            generics: tparams,
843            ..SigParts::default()
844        });
845    }
846    if let Some(t) = ty {
847        match kind {
848            ApiKind::Struct => {
849                let mut c = t.walk();
850                if let Some(list) = t
851                    .named_children(&mut c)
852                    .find(|n| n.kind() == "field_declaration_list")
853                {
854                    it.members = fields(&list, src);
855                }
856            }
857            ApiKind::Interface => it.members = interface_members(&t, src),
858            _ => {}
859        }
860    }
861    it
862}
863
864fn fields(list: &Node, src: &str) -> Vec<ApiItem> {
865    let mut out = Vec::new();
866    for (f, doc) in specs(list, src, &["field_declaration"]) {
867        let ty = f
868            .child_by_field_name("type")
869            .map(|n| clean(&n, src))
870            .unwrap_or_default();
871        let tag = f
872            .child_by_field_name("tag")
873            .map(|n| format!(" {}", text(&n, src)))
874            .unwrap_or_default();
875        let mut c = f.walk();
876        let names: Vec<String> = f
877            .children_by_field_name("name", &mut c)
878            .map(|n| text(&n, src).to_string())
879            .collect();
880        if names.is_empty() {
881            // Embedded field: named by its type.
882            let mut it = new_item(
883                base_type_name(&ty).to_string(),
884                ApiKind::Field,
885                &f,
886                doc.as_ref().map(clone_doc),
887            );
888            it.signature = clean(&f, src);
889            it.attrs.push("embedded".into());
890            out.push(it);
891            continue;
892        }
893        for name in names {
894            let mut it = new_item(
895                name.clone(),
896                ApiKind::Field,
897                &f,
898                doc.as_ref().map(clone_doc),
899            );
900            it.signature = format!("{name} {ty}{tag}");
901            out.push(it);
902        }
903    }
904    out
905}
906
907fn interface_members(iface: &Node, src: &str) -> Vec<ApiItem> {
908    let mut out = Vec::new();
909    for (m, doc) in specs(iface, src, &["method_elem", "type_elem"]) {
910        if m.kind() == "method_elem" {
911            let name = m
912                .child_by_field_name("name")
913                .map(|n| text(&n, src).to_string())
914                .unwrap_or_default();
915            let mut it = new_item(name, ApiKind::Method, &m, doc);
916            it.signature = clean(&m, src);
917            it.sig = Some(sig_parts(&m, src));
918            out.push(it);
919        } else {
920            // An embedded interface or a type-set term: `io.Reader`, `~int | ~string`.
921            let t = clean(&m, src);
922            let simple = !t.contains(['|', '~']);
923            let name = if simple {
924                base_type_name(&t).to_string()
925            } else {
926                t.clone()
927            };
928            let mut it = new_item(name, ApiKind::Field, &m, doc);
929            if !simple {
930                it.visibility = Visibility::Inherited;
931            }
932            it.signature = t;
933            it.attrs.push("embedded".into());
934            out.push(it);
935        }
936    }
937    out
938}
939
940fn value_decl(node: &Node, src: &str, decl_doc: Option<Doc>, out: &mut Vec<ApiItem>) {
941    let is_const = node.kind() == "const_declaration";
942    let (keyword, kind, spec_kind) = if is_const {
943        ("const", ApiKind::Const, "const_spec")
944    } else {
945        ("var", ApiKind::Static, "var_spec")
946    };
947    let grouped = is_grouped(node);
948    let mut decl_doc = decl_doc;
949    // Implicit repetition in const groups: `B` after `A Kind = iota` has type `Kind`.
950    let mut last_type: Option<String> = None;
951    let mut first_done = false;
952    for (spec, doc) in specs(node, src, &[spec_kind]) {
953        let ty = spec.child_by_field_name("type").map(|n| clean(&n, src));
954        let value = spec.child_by_field_name("value");
955        let ty = match (&ty, value) {
956            (Some(_), _) => {
957                last_type = ty.clone();
958                ty
959            }
960            (None, Some(_)) => {
961                last_type = None;
962                None
963            }
964            (None, None) if is_const => last_type.clone(),
965            (None, None) => None,
966        };
967        let values: Vec<String> = value
968            .map(|v| {
969                let mut c = v.walk();
970                v.named_children(&mut c)
971                    .filter(|n| n.kind() != "comment")
972                    .map(|n| clean(&n, src))
973                    .collect()
974            })
975            .unwrap_or_default();
976        let mut c = spec.walk();
977        let names: Vec<String> = spec
978            .children_by_field_name("name", &mut c)
979            .filter(|n| n.kind() == "identifier")
980            .map(|n| text(&n, src).to_string())
981            .collect();
982        let has_own = doc.as_ref().is_some_and(|d| d.doc.is_some());
983        // The declaration's doc goes to its first spec, unless that has its own.
984        let group_doc = decl_doc.take();
985        let mut doc = if has_own || first_done {
986            doc
987        } else {
988            group_doc.or(doc)
989        };
990        first_done = true;
991        let span = if grouped { spec } else { *node };
992        for (i, name) in names.iter().enumerate() {
993            if name == "_" {
994                continue;
995            }
996            let mut it = new_item(name.clone(), kind, &span, doc.take());
997            let mut sig = format!("{keyword} {name}");
998            if let Some(t) = &ty {
999                sig.push(' ');
1000                sig.push_str(t);
1001            }
1002            let v = if values.len() == names.len() {
1003                values.get(i).cloned()
1004            } else if !values.is_empty() {
1005                Some(values.join(", "))
1006            } else {
1007                None
1008            };
1009            if let Some(v) = v {
1010                if v.chars().count() <= MAX_VALUE {
1011                    sig.push_str(&format!(" = {v}"));
1012                } else {
1013                    sig.push_str(" = …");
1014                }
1015            }
1016            it.signature = sig;
1017            out.push(it);
1018        }
1019    }
1020}
1021
1022#[cfg(test)]
1023mod tests {
1024    use super::*;
1025
1026    fn find<'a>(items: &'a [ApiItem], name: &str) -> &'a ApiItem {
1027        items.iter().find(|i| i.name == name).unwrap_or_else(|| {
1028            panic!(
1029                "{name} not found in {:?}",
1030                items.iter().map(|i| &i.name).collect::<Vec<_>>()
1031            )
1032        })
1033    }
1034
1035    const SAMPLE: &str = r#"// Copyright 2024 The Authors.
1036
1037//go:build linux
1038
1039// Package client talks to the server.
1040//
1041// Start with [NewClient] and [Client.Do].
1042package client
1043
1044import (
1045	"context"
1046	"io"
1047)
1048
1049// Client sends requests.
1050//
1051// # Retries
1052//
1053// A client retries idempotent requests:
1054//
1055//	c := client.NewClient(opts...)
1056//	c.Do(ctx, req)
1057//
1058// Options:
1059//   - [WithTimeout] sets a timeout
1060//   - [io.Reader] bodies are streamed,
1061//     not buffered
1062//
1063// See [Option] and [*http.Client]; x[i] is not a link.
1064type Client struct {
1065	// BaseURL is the root of every request.
1066	BaseURL string `json:"base_url" yaml:"baseURL"`
1067	io.Reader
1068	*Pool
1069	a, B int // trailing field comment
1070	inner bool
1071}
1072
1073// Do sends req.
1074//
1075// Deprecated: use [Client.Send] instead.
1076func (c *Client) Do(ctx context.Context, req *Request) (*Response, error) {
1077	return nil, nil
1078}
1079
1080func (l *List[K, V]) Len() int { return 0 }
1081
1082// Map applies f to every element.
1083func Map[T, U any](xs []T, f func(T) U, extra ...string) []U {
1084	return nil
1085}
1086
1087// Kind is a request kind.
1088type Kind int
1089
1090// Kinds of request.
1091const (
1092	// Get reads.
1093	Get Kind = iota
1094	Put
1095	post
1096	Delete // removes
1097)
1098
1099const Single = "one"
1100
1101var (
1102	ErrClosed = errors.New("closed")
1103	Table     = map[string]int{"a": 1, "b": 2, "c": 3, "d": 4, "e": 5, "f": 6, "g": 7, "h": 8, "i": 9}
1104)
1105
1106// ReadCloser reads and closes.
1107type ReadCloser interface {
1108	io.Reader
1109	// Close closes.
1110	Close() error
1111	close2()
1112}
1113
1114// Number is a constraint.
1115type Number interface {
1116	~int | ~float64
1117}
1118
1119type (
1120	// ID identifies.
1121	ID string
1122	Alias = ID
1123)
1124
1125/*
1126Handler handles.
1127It is a block comment.
1128*/
1129type Handler func(w io.Writer) error
1130"#;
1131
1132    #[test]
1133    fn package_doc_and_name() {
1134        let f = extract(SAMPLE).unwrap();
1135        assert_eq!(f.package.as_deref(), Some("client"));
1136        let d = f.module_doc.as_ref().unwrap();
1137        assert_eq!(d.summary, "Package client talks to the server.");
1138        assert!(
1139            d.markdown
1140                .contains("Start with [`NewClient`] and [`Client.Do`]."),
1141            "{}",
1142            d.markdown
1143        );
1144        assert_eq!(d.links, vec!["NewClient", "Client.Do"]);
1145        assert!(!d.markdown.contains("Copyright"));
1146        assert!(!d.markdown.contains("go:build"));
1147    }
1148
1149    #[test]
1150    fn doc_comment_conversion() {
1151        let f = extract(SAMPLE).unwrap();
1152        let c = find(&f.items, "Client");
1153        let d = c.doc.as_ref().unwrap();
1154        assert_eq!(d.summary, "Client sends requests.");
1155        let md = &d.markdown;
1156        assert!(md.contains("\n# Retries\n"), "{md}");
1157        assert!(
1158            md.contains("```go\nc := client.NewClient(opts...)\nc.Do(ctx, req)\n```"),
1159            "{md}"
1160        );
1161        assert!(
1162            md.contains("- [`WithTimeout`] sets a timeout\n- [`io.Reader`] bodies are streamed, not buffered"),
1163            "{md}"
1164        );
1165        assert!(
1166            md.contains("See [`Option`] and \\*[`http.Client`]; x[i] is not a link."),
1167            "{md}"
1168        );
1169        assert_eq!(d.sections[0].0, "retries");
1170        assert_eq!(d.examples[0].lang, "go");
1171        assert!(d.links.contains(&"http.Client".to_string()));
1172    }
1173
1174    #[test]
1175    fn struct_fields_tags_and_embedding() {
1176        let f = extract(SAMPLE).unwrap();
1177        let c = find(&f.items, "Client");
1178        assert_eq!(c.kind, ApiKind::Struct);
1179        assert_eq!(c.signature, "type Client struct");
1180        assert_eq!(c.visibility, Visibility::Public);
1181        let names: Vec<&str> = c.members.iter().map(|m| m.name.as_str()).collect();
1182        assert_eq!(names, vec!["BaseURL", "Reader", "Pool", "a", "B", "inner"]);
1183        let base = &c.members[0];
1184        assert_eq!(
1185            base.signature,
1186            r#"BaseURL string `json:"base_url" yaml:"baseURL"`"#
1187        );
1188        assert_eq!(
1189            base.doc.as_ref().unwrap().summary,
1190            "BaseURL is the root of every request."
1191        );
1192        assert_eq!(c.members[1].signature, "io.Reader");
1193        assert_eq!(c.members[2].signature, "*Pool");
1194        assert_eq!(c.members[3].visibility, Visibility::Private);
1195        assert_eq!(c.members[4].signature, "B int");
1196        assert_eq!(
1197            c.members[4].doc.as_ref().unwrap().summary,
1198            "trailing field comment"
1199        );
1200    }
1201
1202    #[test]
1203    fn methods_and_generics() {
1204        let f = extract(SAMPLE).unwrap();
1205        let d = find(&f.items, "Do");
1206        assert_eq!(d.kind, ApiKind::Method);
1207        assert_eq!(d.self_type.as_deref(), Some("Client"));
1208        assert_eq!(
1209            d.signature,
1210            "func (c *Client) Do(ctx context.Context, req *Request) (*Response, error)"
1211        );
1212        let sig = d.sig.as_ref().unwrap();
1213        assert_eq!(sig.receiver.as_deref(), Some("c *Client"));
1214        assert_eq!(sig.params.len(), 2);
1215        assert_eq!(sig.params[1].name, "req");
1216        assert_eq!(sig.params[1].ty, "*Request");
1217        assert_eq!(sig.returns.as_deref(), Some("(*Response, error)"));
1218        let dep = d.deprecated.as_ref().unwrap();
1219        assert_eq!(dep.note.as_deref(), Some("use [Client.Send] instead."));
1220        assert!(!d.doc.as_ref().unwrap().markdown.contains("Deprecated"));
1221
1222        let len = find(&f.items, "Len");
1223        assert_eq!(len.self_type.as_deref(), Some("List"));
1224        assert_eq!(len.signature, "func (l *List[K, V]) Len() int");
1225
1226        let m = find(&f.items, "Map");
1227        assert_eq!(m.kind, ApiKind::Function);
1228        let sig = m.sig.as_ref().unwrap();
1229        assert_eq!(sig.generics.as_deref(), Some("[T, U any]"));
1230        let p: Vec<(&str, &str)> = sig
1231            .params
1232            .iter()
1233            .map(|p| (p.name.as_str(), p.ty.as_str()))
1234            .collect();
1235        assert_eq!(
1236            p,
1237            vec![("xs", "[]T"), ("f", "func(T) U"), ("extra", "...string")]
1238        );
1239        assert_eq!(sig.returns.as_deref(), Some("[]U"));
1240    }
1241
1242    #[test]
1243    fn grouped_consts_with_iota_and_vars() {
1244        let f = extract(SAMPLE).unwrap();
1245        let get = find(&f.items, "Get");
1246        assert_eq!(get.kind, ApiKind::Const);
1247        assert_eq!(get.signature, "const Get Kind = iota");
1248        assert_eq!(get.doc.as_ref().unwrap().summary, "Get reads.");
1249        let put = find(&f.items, "Put");
1250        assert_eq!(put.signature, "const Put Kind");
1251        assert!(put.doc.is_none(), "the group doc goes to one spec only");
1252        assert_eq!(find(&f.items, "post").visibility, Visibility::Private);
1253        let del = find(&f.items, "Delete");
1254        assert_eq!(del.doc.as_ref().unwrap().summary, "removes");
1255        assert_eq!(
1256            find(&f.items, "Single").signature,
1257            r#"const Single = "one""#
1258        );
1259
1260        let err = find(&f.items, "ErrClosed");
1261        assert_eq!(err.kind, ApiKind::Static);
1262        assert_eq!(err.signature, r#"var ErrClosed = errors.New("closed")"#);
1263        assert_eq!(find(&f.items, "Table").signature, "var Table = …");
1264    }
1265
1266    #[test]
1267    fn interfaces_and_named_types() {
1268        let f = extract(SAMPLE).unwrap();
1269        let rc = find(&f.items, "ReadCloser");
1270        assert_eq!(rc.kind, ApiKind::Interface);
1271        assert_eq!(rc.signature, "type ReadCloser interface");
1272        let names: Vec<(&str, ApiKind)> = rc
1273            .members
1274            .iter()
1275            .map(|m| (m.name.as_str(), m.kind))
1276            .collect();
1277        assert_eq!(
1278            names,
1279            vec![
1280                ("Reader", ApiKind::Field),
1281                ("Close", ApiKind::Method),
1282                ("close2", ApiKind::Method)
1283            ]
1284        );
1285        assert_eq!(rc.members[0].signature, "io.Reader");
1286        assert_eq!(rc.members[1].signature, "Close() error");
1287        assert_eq!(rc.members[1].doc.as_ref().unwrap().summary, "Close closes.");
1288        assert_eq!(rc.members[2].visibility, Visibility::Private);
1289
1290        let n = find(&f.items, "Number");
1291        assert_eq!(n.members[0].name, "~int | ~float64");
1292        assert_eq!(n.members[0].visibility, Visibility::Inherited);
1293
1294        let kind = find(&f.items, "Kind");
1295        assert_eq!(kind.kind, ApiKind::TypeAlias);
1296        assert_eq!(kind.signature, "type Kind int");
1297        let id = find(&f.items, "ID");
1298        assert_eq!(id.signature, "type ID string");
1299        assert_eq!(id.doc.as_ref().unwrap().summary, "ID identifies.");
1300        let alias = find(&f.items, "Alias");
1301        assert_eq!(alias.kind, ApiKind::TypeAlias);
1302        assert_eq!(alias.signature, "type Alias = ID");
1303        let h = find(&f.items, "Handler");
1304        assert_eq!(h.signature, "type Handler func(w io.Writer) error");
1305        assert_eq!(
1306            h.doc.as_ref().unwrap().markdown,
1307            "Handler handles.\nIt is a block comment."
1308        );
1309    }
1310
1311    #[test]
1312    fn escaping_and_sentences() {
1313        let mut links = Vec::new();
1314        assert_eq!(
1315            inline("returns *T or <nil>, `a*b` stays", &mut links, true),
1316            "returns \\*T or \\<nil>, `a*b` stays"
1317        );
1318        assert_eq!(
1319            inline("snake_case and _x", &mut links, true),
1320            "snake_case and \\_x"
1321        );
1322        assert_eq!(
1323            first_sentence("Handles U.S. data. More."),
1324            "Handles U.S. data."
1325        );
1326        assert_eq!(first_sentence("No period"), "No period");
1327        assert_eq!(escape_line_start("# not heading"), "\\# not heading");
1328        assert!(is_directive("go:generate stringer"));
1329        assert!(is_directive("nolint:errcheck"));
1330        assert!(!is_directive(" Note: this"));
1331        assert!(!doc_link_target("i"));
1332        assert!(doc_link_target("pkg.Name.Method"));
1333    }
1334
1335    #[test]
1336    fn testable_examples() {
1337        let src = "package client_test\n\n// Basic use.\nfunc ExampleClient_Do() {\n\tc := New()\n\tfmt.Println(c.Do())\n\t// Output: ok\n}\n\nfunc Example() {}\n\nfunc Examplelower() {}\n\nfunc ExampleHelper(t int) {}\n";
1338        let ex = examples(src).unwrap();
1339        let names: Vec<&str> = ex.iter().map(|e| e.name.as_str()).collect();
1340        assert_eq!(names, vec!["Client_Do", ""]);
1341        assert_eq!(ex[0].code, "c := New()\nfmt.Println(c.Do())\n// Output: ok");
1342        assert_eq!(ex[0].doc.as_deref(), Some("Basic use."));
1343    }
1344
1345    #[test]
1346    fn signatures_drop_comments_and_split_names() {
1347        let src = "package p\n\n// Copy copies.\n//\n//go:noinline\nfunc Copy(\n\tdst, src []byte, // buffers\n\t/* inline */ n int,\n) (written int, err error) {\n\treturn 0, nil\n}\n\ntype Tagged struct {\n\tURL string `json:\"url\" // not a comment`\n}\n";
1348        let f = extract(src).unwrap();
1349        let c = find(&f.items, "Copy");
1350        assert_eq!(
1351            c.signature,
1352            "func Copy( dst, src []byte, n int, ) (written int, err error)"
1353        );
1354        assert_eq!(c.doc.as_ref().unwrap().markdown, "Copy copies.");
1355        let sig = c.sig.as_ref().unwrap();
1356        let p: Vec<(&str, &str)> = sig
1357            .params
1358            .iter()
1359            .map(|p| (p.name.as_str(), p.ty.as_str()))
1360            .collect();
1361        assert_eq!(p, vec![("dst", "[]byte"), ("src", "[]byte"), ("n", "int")]);
1362        assert_eq!(sig.returns.as_deref(), Some("(written int, err error)"));
1363        let t = find(&f.items, "Tagged");
1364        assert_eq!(
1365            t.members[0].signature,
1366            "URL string `json:\"url\" // not a comment`"
1367        );
1368    }
1369
1370    /// Extract every non-test `.go` file under `$REFLEX_GO_TREE` (default: a Kubernetes
1371    /// checkout), skipping `vendor/`. Read-only. Run with `--ignored --nocapture`.
1372    #[test]
1373    #[ignore]
1374    fn extract_go_tree() {
1375        let root = std::env::var("REFLEX_GO_TREE").unwrap_or_else(|_| {
1376            format!(
1377                "{}/Code/misc/test/kubernetes",
1378                std::env::var("HOME").unwrap_or_default()
1379            )
1380        });
1381        fn walk(dir: &std::path::Path, out: &mut Vec<std::path::PathBuf>) {
1382            let Ok(rd) = std::fs::read_dir(dir) else {
1383                return;
1384            };
1385            for e in rd.flatten() {
1386                let p = e.path();
1387                let name = e.file_name().to_string_lossy().to_string();
1388                if p.is_dir() {
1389                    if !name.starts_with('.') && name != "vendor" {
1390                        walk(&p, out);
1391                    }
1392                } else if name.ends_with(".go") && !name.ends_with("_test.go") {
1393                    out.push(p);
1394                }
1395            }
1396        }
1397        let mut files = Vec::new();
1398        walk(std::path::Path::new(&root), &mut files);
1399        let sources: Vec<String> = files
1400            .iter()
1401            .filter_map(|f| std::fs::read_to_string(f).ok())
1402            .collect();
1403        let start = std::time::Instant::now();
1404        let (mut items, mut documented, mut public, mut failed) = (0, 0, 0, 0);
1405        fn count(items: &[ApiItem], n: &mut usize, d: &mut usize, p: &mut usize) {
1406            for i in items {
1407                *n += 1;
1408                if i.doc.is_some() {
1409                    *d += 1;
1410                }
1411                if i.visibility == Visibility::Public {
1412                    *p += 1;
1413                }
1414                count(&i.members, n, d, p);
1415            }
1416        }
1417        for src in &sources {
1418            match extract(src) {
1419                Ok(api) => count(&api.items, &mut items, &mut documented, &mut public),
1420                Err(_) => failed += 1,
1421            }
1422        }
1423        println!(
1424            "{} files ({failed} failed), {items} items ({documented} documented, {public} exported) in {:?}",
1425            sources.len(),
1426            start.elapsed()
1427        );
1428    }
1429}