Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

doc-links(php): a property's, constant's or case's doc block belongs to its type

Martin Vogel2fdcbfe28828
diff --git a/internal/cbm/doclink.c b/internal/cbm/doclink.c
index 18a65cef1..8c6612b0e 100644
--- a/internal/cbm/doclink.c
+++ b/internal/cbm/doclink.c
@@ -251,7 +251,8 @@ static const doclink_lang_t DOCLINK_LANGS[] = {
.parse_doc = cbm_doclink_php_parse_doc,
.scan_scope = cbm_doclink_php_scan_scope,
.scope_tag = CBM_DOCLINK_PHP_SCOPE_TAG,
- .portable_scope = cbm_doclink_php_portable_scope},
+ .portable_scope = cbm_doclink_php_portable_scope,
+ .loose_docs = cbm_doclink_php_loose_docs},
};
static const doclink_lang_t *doclink_lang(CBMLanguage lang) {
@@ -480,10 +481,11 @@ static bool doclink_taken(const CBMExtractCtx *ctx, uint32_t first, uint32_t las
return false;
}
-/* The file's own doc, then the language's loose docs: their references belong
- * to the file. The parser gets a definition-shaped stand-in for the file; what
- * it pushes is marked, and the resolving half takes the File node as the
- * source. No qualified name for that node is computed on this side. */
+/* The file's own doc, then the language's loose docs. The parser gets a
+ * definition-shaped stand-in for the file; what it pushes with the stand-in
+ * is marked, and the resolving half takes the File node as the source (a
+ * loose-doc hook may push with a definition of the file instead). No qualified
+ * name for that node is computed on this side. */
static void doclink_file_pass(CBMExtractCtx *ctx, const doclink_lang_t *L) {
const char *file_doc = ctx->result->module_doc;
bool has_doc = file_doc && file_doc[0];
@@ -513,7 +515,9 @@ static void doclink_file_pass(CBMExtractCtx *ctx, const doclink_lang_t *L) {
L->loose_docs(ctx, &file_def, doclink_taken);
}
for (int i = first; i < arr->count; i++) {
- arr->items[i].flags |= CBM_DOCLINK_FLAG_FILE;
+ if (arr->items[i].source_qn == file_def.qualified_name) {
+ arr->items[i].flags |= CBM_DOCLINK_FLAG_FILE; /* not a definition's */
+ }
}
}
diff --git a/internal/cbm/doclink.h b/internal/cbm/doclink.h
index cce493488..faccd4dcf 100644
--- a/internal/cbm/doclink.h
+++ b/internal/cbm/doclink.h
@@ -23,9 +23,11 @@
* scope_tag, the blob's tag line and its persisted form (line
* portable_scope numbers dropped). Optional.
* loose_docs after the definitions and the file's own doc: the
- * file's other doc comments (C: a prototype's doc,
- * which the graph keeps no node for); what it pushes
- * belongs to the file. Optional.
+ * file's other doc comments, which the graph keeps no
+ * node for. What it pushes with the file stand-in
+ * belongs to the file (C: a prototype's doc); it may push
+ * with a definition of the file instead (PHP: a
+ * property's doc belongs to its class). Optional.
* scan_file instead of parse_doc, for a DOCUMENT language whose
* text is the documentation (Markdown): one pass over
* the file's bytes pushes every reference, with the
@@ -564,12 +566,20 @@ char *cbm_doclink_ts_portable_scope(const char *scope);
* this length and the resolver reports it as unparseable. */
enum { CBM_DOCLINK_TS_REF_MAX = 512 };
+/* Asked by a loose_docs hook for a doc comment on lines [first, last]: true
+ * when a definition's doc or the file's own doc there was already taken. */
+typedef bool (*cbm_doclink_taken_fn)(const CBMExtractCtx *ctx, uint32_t first, uint32_t last);
+
/* ── PHP (doclink_php.c) ───────────────────────────────────────────── */
void cbm_doclink_php_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,
uint32_t doc_line);
const char *cbm_doclink_php_scan_scope(CBMExtractCtx *ctx);
char *cbm_doclink_php_portable_scope(const char *scope);
+/* Doc blocks on properties, class constants and enum cases (they have no
+ * node): their references belong to the type around them. */
+void cbm_doclink_php_loose_docs(CBMExtractCtx *ctx, const CBMDefinition *file_def,
+ cbm_doclink_taken_fn taken);
#define CBM_DOCLINK_PHP_SCOPE_TAG "php1"
@@ -600,10 +610,6 @@ size_t cbm_doclink_php_qualify(char *out, size_t cap, const char *ns, size_t ns_
/* ── C (doclink_c.c) ───────────────────────────────────────────────── */
-/* Asked by a loose_docs hook for a doc comment on lines [first, last]: true
- * when a definition's doc or the file's own doc there was already taken. */
-typedef bool (*cbm_doclink_taken_fn)(const CBMExtractCtx *ctx, uint32_t first, uint32_t last);
-
void cbm_doclink_c_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,
uint32_t doc_line);
void cbm_doclink_c_loose_docs(CBMExtractCtx *ctx, const CBMDefinition *file_def,
diff --git a/internal/cbm/doclink_php.c b/internal/cbm/doclink_php.c
index 8abb8a437..35f14788e 100644
--- a/internal/cbm/doclink_php.c
+++ b/internal/cbm/doclink_php.c
@@ -37,6 +37,10 @@
* flags as for T
* "At the top level" includes the branches of a top-level conditional
* (`if (!function_exists('f')) { function f() {} }`), never a function body.
+ * Doc blocks on properties, class constants and enum cases, which have no
+ * node, go through cbm_doclink_php_loose_docs: their references belong to
+ * the type around them.
+ *
* The persisted blob (cbm_doclink_php_portable_scope) drops the lines of N
* and T and the U records: other files read names only, and every name a
* supertype record holds is already qualified.
@@ -910,6 +914,111 @@ const char *cbm_doclink_php_scan_scope(CBMExtractCtx *ctx) {
return sb.oom ? NULL : sb.buf;
}
+/* ── Loose docs ──────────────────────────────────────────────────── */
+
+/* The definition of a type declaration: its name, at its line. */
+static const CBMDefinition *php_type_def(const CBMExtractCtx *ctx, TSNode decl) {
+ TSNode name = ts_node_child_by_field_name(decl, TS_FIELD("name"));
+ if (ts_node_is_null(name)) {
+ return NULL;
+ }
+ uint32_t b = ts_node_start_byte(name);
+ size_t n = ts_node_end_byte(name) - b;
+ uint32_t line = ts_node_start_point(decl).row + SKIP_ONE;
+ const CBMDefArray *defs = &ctx->result->defs;
+ for (int i = 0; i < defs->count; i++) {
+ const CBMDefinition *d = &defs->items[i];
+ if (d->name && d->qualified_name && d->start_line == line && strlen(d->name) == n &&
+ memcmp(d->name, ctx->source + b, n) == 0) {
+ return d;
+ }
+ }
+ return NULL;
+}
+
+static bool php_member_decl(TSNode n) {
+ return php_kind(n, "property_declaration") || php_kind(n, "const_declaration") ||
+ php_kind(n, "enum_case");
+}
+
+static bool php_doc_comment(const CBMExtractCtx *ctx, TSNode n) {
+ if (!php_kind(n, "comment")) {
+ return false;
+ }
+ uint32_t b = ts_node_start_byte(n);
+ size_t len = ts_node_end_byte(n) - b;
+ return len > PHP_PREFIX_LEN + SKIP_ONE && memcmp(ctx->source + b, "/**", PHP_PREFIX_LEN) == 0 &&
+ ctx->source[b + PHP_PREFIX_LEN] != '*';
+}
+
+/* The doc blocks right above a type's properties, constants and cases. */
+static void php_loose_type(CBMExtractCtx *ctx, TSNode decl, cbm_doclink_taken_fn taken) {
+ const CBMDefinition *def = php_type_def(ctx, decl);
+ TSNode body = ts_node_child_by_field_name(decl, TS_FIELD("body"));
+ if (!def || ts_node_is_null(body)) {
+ return;
+ }
+ TSNode doc = {0};
+ TSTreeCursor cur = ts_tree_cursor_new(body);
+ for (bool more = ts_tree_cursor_goto_first_child(&cur); more;
+ more = ts_tree_cursor_goto_next_sibling(&cur)) {
+ TSNode c = ts_tree_cursor_current_node(&cur);
+ if (!ts_node_is_named(c)) {
+ continue;
+ }
+ if (php_doc_comment(ctx, c)) {
+ doc = c;
+ continue;
+ }
+ uint32_t first = ts_node_is_null(doc) ? 0 : ts_node_start_point(doc).row + SKIP_ONE;
+ uint32_t last = ts_node_is_null(doc) ? 0 : ts_node_end_point(doc).row + SKIP_ONE;
+ if (first && php_member_decl(c) &&
+ ts_node_start_point(c).row + SKIP_ONE <= last + SKIP_ONE && !taken(ctx, first, last)) {
+ CBMArena *a = ctx->scratch ? ctx->scratch : ctx->arena;
+ uint32_t b = ts_node_start_byte(doc);
+ char *text = cbm_arena_strndup(a, ctx->source + b, ts_node_end_byte(doc) - b);
+ if (text) {
+ cbm_doclink_php_parse_doc(ctx, def, text, first);
+ }
+ }
+ doc = (TSNode){0};
+ }
+ ts_tree_cursor_delete(&cur);
+}
+
+/* The types of the file: top level, namespace bodies, top-level conditionals. */
+static void php_loose_walk(CBMExtractCtx *ctx, TSNode parent, int depth,
+ cbm_doclink_taken_fn taken) {
+ if (depth > PHP_COND_DEPTH) {
+ return;
+ }
+ TSTreeCursor cur = ts_tree_cursor_new(parent);
+ for (bool more = ts_tree_cursor_goto_first_child(&cur); more;
+ more = ts_tree_cursor_goto_next_sibling(&cur)) {
+ TSNode c = ts_tree_cursor_current_node(&cur);
+ if (php_is_type_decl(c)) {
+ php_loose_type(ctx, c, taken);
+ } else if (php_kind(c, "namespace_definition")) {
+ TSNode body = ts_node_child_by_field_name(c, TS_FIELD("body"));
+ if (!ts_node_is_null(body)) {
+ php_loose_walk(ctx, body, depth + SKIP_ONE, taken);
+ }
+ } else if (php_is_branch(c)) {
+ php_loose_walk(ctx, c, depth + SKIP_ONE, taken);
+ }
+ }
+ ts_tree_cursor_delete(&cur);
+}
+
+void cbm_doclink_php_loose_docs(CBMExtractCtx *ctx, const CBMDefinition *file_def,
+ cbm_doclink_taken_fn taken) {
+ (void)file_def; /* a member's doc belongs to its type, never to the file */
+ if (!ctx || !ctx->result || !taken || ts_node_is_null(ctx->root)) {
+ return;
+ }
+ php_loose_walk(ctx, ctx->root, 0, taken);
+}
+
/* The blob without lines and imports: "N blk name first last" -> "N blk
* name", "T kind fqn flags first last" -> "T kind fqn flags", U dropped. */
char *cbm_doclink_php_portable_scope(const char *scope) {
diff --git a/tests/test_doc_mentions_php.c b/tests/test_doc_mentions_php.c
index c4342d90d..c1352b0e5 100644
--- a/tests/test_doc_mentions_php.c
+++ b/tests/test_doc_mentions_php.c
@@ -193,13 +193,16 @@ static void php_write_repo(const char *repo) {
"class Numbers { const MAX = 9; }\n"
"trait Loud { public function shout() {} }\n"
"function clamp($v) { return $v; }\n");
- th_write_file(TH_PATH(repo, "src/Model/Base.php"), "<?php\n"
- "namespace App\\Model;\n"
- "\n"
- "abstract class Base {\n"
- " public function boot() {}\n"
- " public function mixedCase() {}\n"
- "}\n");
+ th_write_file(TH_PATH(repo, "src/Model/Base.php"),
+ "<?php\n"
+ "namespace App\\Model;\n"
+ "\n"
+ "abstract class Base {\n"
+ " /** The hook, {@see \\App\\Util\\Strings}. */\n"
+ " protected $hook;\n"
+ " public function boot() {}\n"
+ " public function mixedCase() {}\n"
+ "}\n");
th_write_file(TH_PATH(repo, "src/Dup.php"), "<?php\n"
"namespace App\\One;\n"
"class Same {}\n"
@@ -323,6 +326,8 @@ TEST(doc_mentions_php_resolution) {
ASSERT_TRUE(php_row(db, "\\App\\Twin\\Twin", "ambiguous"));
ASSERT_TRUE(php_row(db, "\\App\\One\\Same", "graph_gap"));
ASSERT_TRUE(php_row(db, "\\App\\One\\same()", "graph_gap"));
+ /* a property's doc block belongs to its class */
+ ASSERT_TRUE(php_edge(db, "src.Model.Base.Base", "src.Util.Helper.Strings"));
/* aliases and method names compare without case */
ASSERT_TRUE(php_edge(db, "src.Model.User.User.other", "src.Util.Helper.Helper.format"));
PASS();