1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
//! `Checker` implementation for PHP.
#![allow(clippy::wildcard_imports, clippy::enum_glob_use)]
use super::*;
use crate::lang_helpers::doc_comment::never_joins;
/// A top-level node phpDocumentor's `createFileDocBlock` passes over
/// looking for the file's first element: `Declare_` and `InlineHTML`, which
/// tree-sitter-php spells as a `declare` statement and the `<?php` / `?>`
/// text around inline HTML.
fn php_file_preamble(node: &Node) -> bool {
matches!(
node.kind_id().into(),
Php::PhpTag | Php::Text | Php::TextInterpolation | Php::DeclareStatement
)
}
/// Whether `comment` is phpDocumentor's file DocBlock (#1613), which
/// documents the file wherever it sits. `createFileDocBlock` gathers the
/// comments before the first top-level node that is not a preamble; if that
/// node is not a class, function, constant, interface or trait, the first
/// DocBlock among them is the file's, and otherwise it is only when exactly
/// two DocBlocks precede it. The backward test stops at the previous
/// DocBlock, so only the file's first one scans forward.
fn php_file_docblock<'a>(comment: &Node<'a>, code: &[u8], ancestors: Ancestors<'a, '_>) -> bool {
let preamble_or_plain = |n: Node| {
php_file_preamble(&n) || (PhpCode::is_comment(&n) && !PhpCode::is_doc_comment(&n, code))
};
if !ancestors.parent_has_kind(comment, Php::Program as u16)
|| !ancestors.siblings_before(comment).all(preamble_or_plain)
{
return false;
}
let mut docs = 1_usize;
for node in ancestors.siblings_after(comment) {
if PhpCode::is_doc_comment(&node, code) {
docs += 1;
} else if !PhpCode::is_comment(&node) && !php_file_preamble(&node) {
return docs == 2
// role-bypass: allow(DocTarget, FuncOpener, Container, Member) — the subset
// of targets `createFileDocBlock` treats as the file's first element: a
// selection policy over the row, not membership
|| !matches!(
node.kind_id().into(),
Php::ClassDeclaration
| Php::FunctionDefinition
| Php::ConstDeclaration
| Php::ConstDeclaration2
| Php::InterfaceDeclaration
| Php::TraitDeclaration
);
}
}
true
}
impl Checker for PhpCode {
// The `Comment` and `DocComment` rows of `roles/php.rs` (#1699):
// the one comment kind, a DocBlock under PHP's marker.
impl_comment_from_rows!(php);
impl_doc_comment_from_row!(php);
// phpDocumentor gives an element PHP-Parser's `getDocComment`: the
// last DocBlock among the comments before the node's first token, so
// plain comments in between are read past and only the last of several
// DocBlocks documents it (#1613). A DocBlock among a declaration's own
// children — after its `#[…]` attributes, before its body, on a
// promoted parameter — is the one `ReflectionFunction::getDocComment`
// reads, decided as before (#1612), as is the file DocBlock, which
// documents the file rather than what follows. A property, a constant
// and an enum case hold their `#[…]` attributes as children too, so
// each is a declaration here like a method.
const DOC_BINDING: Option<DocBinding> = Some(DocBinding {
forward: |comment, code, ancestors| {
let in_signature = ancestors.parent(comment).is_some_and(|parent| {
let kind = parent.kind_id();
// The declarations are the `DocTarget` row's kind table,
// less the `define()` statement: a DocBlock among an
// expression statement's children sits after its
// expression, where PHP-Parser gives it to the token
// after it, as `/** d */ $x = 1;` does (#1646). Beside
// the declarations the closures, a parameter list and a
// promoted parameter, which hold a DocBlock in a
// signature without being targets themselves.
// role-bypass: allow(DocTarget) — the row's declaration owners, which hold
// their DocBlock as a child after `#[…]` attributes; the statement owner
// holds no declaration children, so it is left out of the signature set
let declaration = crate::roles::php::doc_target::lists_kind(kind)
&& kind != Php::ExpressionStatement;
// role-bypass: allow(Closure) — a DocBlock *inside* a closure is in
// its signature; where a declaration's children end is a binding
// question, not membership
let signature_holder = matches!(
kind.into(),
Php::AnonymousFunction
| Php::ArrowFunction
| Php::FormalParameters
| Php::PropertyPromotionParameter
);
declaration || signature_holder
});
!in_signature && !php_file_docblock(comment, code, ancestors)
},
..DocBinding::new(KeptDocs::Leading {
hidden: |node, code| !Self::is_doc_comment(node, code),
joins: never_joins,
// PHP-Parser gives a node every comment since the token before
// it, whatever row that token ends on.
after_code: |_| true,
})
});
// The `DocTarget` row of `roles/php.rs` (#1699).
impl_doc_target_from_row!(php);
// PHP's parser binds the last docblock before a function's name to it,
// so one written after `#[...]` attributes still documents it, and a
// promoted constructor property keeps its parameter's docblock
// (`ReflectionProperty::getDocComment`). Only the body is in-body: the
// `compound_statement` child, or an arrow function's expression, which
// is its last child since tree-sitter moves trailing comments out of a
// node — except before a zero-width MISSING body, which leaves the
// comment itself ending where the arrow function does. Decided by
// `below`'s kind and span, because the `body` field lookup walks every
// comment in the signature (#1612).
fn holds_doc_comment_in_body<'a>(
ancestor: &Node<'a>,
_ancestors: Ancestors<'a, '_>,
below: &Node<'a>,
) -> bool {
// role-bypass: allow(FuncOpener, Closure) — which child of an opener is
// its body, not whether the node opens a space; `DocBodyResidual` is
// absent for PHP because nothing beyond the openers holds one
match ancestor.kind_id().into() {
Php::FunctionDefinition | Php::MethodDeclaration | Php::AnonymousFunction => {
below.kind_id() == Php::CompoundStatement
}
Php::ArrowFunction => {
below.end_byte() == ancestor.end_byte() && !Self::is_comment(below)
}
_ => false,
}
}
// The space tree is declared in `roles/php.rs` (#1696): the
// `FuncOpener` and `Container` rows are what the walk promotes and
// `opens_space` labels. The rows read no bytes and no chain, so the
// byte-less spelling forwards with none and answers the same.
impl_byte_less_func_space!(php);
fn is_func_space_with_code<'a>(
node: &Node<'a>,
code: &[u8],
ancestors: Ancestors<'a, '_>,
) -> bool {
crate::roles::php::opens_space(node, code, ancestors) != SpaceKind::Unknown
}
fn is_func<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> bool {
crate::roles::php::func_opener::is_callable(node, &[], ancestors)
}
fn is_closure<'a>(node: &Node<'a>, ancestors: Ancestors<'a, '_>) -> bool {
crate::roles::php::closure::owns(node, &[], ancestors)
}
// `Call` and `StringLit` are the rows of `roles/php.rs` (#1698);
// the byte-less spellings are their kind tables, gates aside.
impl_row_predicates!(php, call, is_call, is_call_with_code);
impl_row_predicates!(php, string_lit, is_string, is_string_with_code);
fn is_non_arg(node: &Node) -> bool {
matches!(
node.kind_id().into(),
Php::LPAREN | Php::LPAREN2 | Php::COMMA | Php::RPAREN | Php::RPAREN2 | Php::DOTDOTDOT
)
}
// The `ElseIf` row of `roles/php.rs` (#529, #1697): the one-word
// `elseif` clause (both aliases) is the else-if itself, and the
// two-word `else if` is an `if_statement` directly inside an
// `else_clause` (either alias). The nested-`if` reading is what lets
// cognitive suppress the nesting penalty while the wrapping clause
// still scores its +1; the row reads no bytes, so the empty code is
// exact.
impl_else_if_from_row!(php);
}