1use 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
21const MAX_SIGNATURE: usize = 600;
23const 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 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#[derive(Debug, Clone, PartialEq)]
77pub struct Example {
78 pub name: String,
80 pub code: String,
82 pub doc: Option<String>,
83}
84
85pub 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 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
149pub 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#[derive(Default)]
164struct CommentGroup {
165 comments: Vec<(usize, usize, Vec<String>)>,
167}
168
169#[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 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
201fn 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
227fn 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
242fn 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
273fn 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
307fn 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
324fn 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 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 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 ¶ {
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
437fn 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
454fn 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
466fn 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
486fn 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 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 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
570fn 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
579fn clean(node: &Node, src: &str) -> String {
581 clean_until(node, src, node.end_byte())
582}
583
584fn 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
624pub 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 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
742fn 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
749fn 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 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 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 _ => 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 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 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 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 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 #[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}