mago_syntax/comments/
docblock.rs

1use mago_database::file::File;
2use mago_span::HasSpan;
3
4use crate::ast::Program;
5use crate::ast::Trivia;
6use crate::ast::TriviaKind;
7
8/// Retrieves the docblock comment associated with a given node in the program.
9/// If the node is preceded by a docblock comment, it returns that comment.
10///
11/// This function searches for the last docblock comment that appears before the node's start position,
12/// ensuring that it is directly preceding the node without any non-whitespace characters in between.
13///
14/// # Arguments
15///
16/// * `program` - The program containing the trivia.
17/// * `file` - The file from which the trivia is derived.
18/// * `node` - The node for which to find the preceding docblock comment.
19///
20/// # Returns
21///
22/// An `Option` containing a reference to the `Trivia` representing the docblock comment if found,
23/// or `None` if no suitable docblock comment exists before the node.
24#[inline]
25pub fn get_docblock_for_node<'arena>(
26    program: &'arena Program<'arena>,
27    file: &File,
28    node: impl HasSpan,
29) -> Option<&'arena Trivia<'arena>> {
30    get_docblock_before_position(file, program.trivia.as_slice(), node.span().start.offset)
31}
32
33/// Retrieves the docblock comment that appears before a specific position in the source code.
34///
35/// This function scans the trivia associated with the source code and returns the last docblock comment
36/// that appears before the specified position, ensuring that it is directly preceding the node
37/// without any non-whitespace characters in between.
38///
39/// # Arguments
40///
41/// * `file` - The file from which the trivia is derived.
42/// * `trivias` - A slice of trivia associated with the source code.
43/// * `node_start_offset` - The start offset of the node for which to find the preceding docblock comment.
44///
45/// # Returns
46///
47/// An `Option` containing a reference to the `Trivia` representing the docblock comment if found,
48pub fn get_docblock_before_position<'arena>(
49    file: &File,
50    trivias: &'arena [Trivia<'arena>],
51    node_start_offset: u32,
52) -> Option<&'arena Trivia<'arena>> {
53    let candidate_partition_idx = trivias.partition_point(|trivia| trivia.span.start.offset < node_start_offset);
54    if candidate_partition_idx == 0 {
55        return None;
56    }
57
58    for i in (0..candidate_partition_idx).rev() {
59        let trivia = &trivias[i];
60
61        match trivia.kind {
62            TriviaKind::DocBlockComment => {
63                let docblock_end_offset = trivia.span().end.offset;
64
65                // Get the slice between docblock end and class start
66                let code_between_slice = file
67                    .contents
68                    .as_bytes()
69                    .get(docblock_end_offset as usize..node_start_offset as usize)
70                    .unwrap_or(&[]);
71
72                if code_between_slice.iter().all(|b| b.is_ascii_whitespace()) {
73                    // It's the correct docblock!
74                    return Some(trivia);
75                } else {
76                    // There was non-whitespace code between this docblock and the class.
77                    // This docblock doesn't apply. Stop searching.
78                    return None;
79                }
80            }
81            TriviaKind::WhiteSpace => {
82                continue;
83            }
84            _ => {
85                return None;
86            }
87        }
88    }
89
90    // Iterated through all preceding trivia without finding a suitable docblock.
91    None
92}
mago_syntax/comments/docblock.rs

mago_syntax/comments/
docblock.rs
