Skip to content

Commit 7a321ca

Browse files
committed
doc-links(php): PHPDoc @see references become MENTIONS edges, held until their audit
A PHP doc block names code with `@see Ref` at the start of a tag line (a description may follow) and with inline `{@see Ref}`, both family `see`. doclink_php.c harvests them (code spans and fenced blocks hold none; @link, @uses and the other tags are not harvested; a URL is the core's href family) and writes each file's scope: namespace blocks, use imports, types with their supertypes already qualified in their own file, members, functions. The persisted scope drops lines and imports: other files read names only. Declarations inside a top-level conditional count as top level (`if (!function_exists('f')) { function f() {} }`), never a function body. doc_links_php.c resolves a reference as a FQSEN with PHP's own name rules: - a leading backslash is taken as written; otherwise the first segment is replaced when it is the alias of a class `use` of the namespace block the reference is written in, else the block's namespace is put in front (phpDocumentor's resolver); - beyond that tool, as PHP itself has them: an unqualified function name is taken from a `use function` import, else from the current namespace, else from the global namespace; and self/static/parent name the documented type and its superclass; - a bare `name()` that would bind a function but is written in a type that declares or inherits a method of that name is ambiguous (the method or the function; the reference does not say which); - members are looked up on the type, its traits, its superclass and its interfaces (depth first); type, function and method names compare without case, properties and constants with it; - properties, class constants and enum cases have no graph node: graph_gap; so has a type or function the graph folds into another one of the same name in its file (two namespace blocks), which the scope flags; - a name the repository does not declare is external outside the repository's namespace roots (built-ins, Composer dependencies), else missing. Residual: a function a dependency declares in the current namespace is invisible, so the fallback would bind a global function of that name. There is no scope_delta hook yet: a declaration change is a full run. The family is held (ships=false) until its held-out audit passes; the suite ships it through the test seam. Proof (ship build, Apple M5 Pro / 48 GB, base 196ca71): - koel 04ed8beaec34 vs the field test's prototype: 4 of its 5 pairs bound alike; the fifth sits in a class constant's doc block, which has no node. - cakephp a75828db: 342 edge mentions + 39 unresolved rows = every one of the 381 non-URL references in function and type doc blocks; 36 more sit in property and constant doc blocks (no node, not harvested). - symfony 9917e115: 452 edge mentions (434 edges) + 205 rows = all 657; 24 in property, constant and other doc blocks. - edges only through the global fallback: 1 (cakephp `@see debug()` in Cake\Core, the global debug() helper: correct); one more on symfony was wrong (`@see run()` meaning the class's own method bound a global script function) and the method-name rule above makes it ambiguous. Through self/static/parent: 20, all correct (12 + 5 self, 3 parent). - a random sample of 24 edges (12 per corpus) read against their source lines: all correct. Tests (doc_mentions_php): tokens with their lines; the scope blob, its persisted form, namespace blocks and conditional declarations; every resolution rule; the global fallback and self/static/parent each in a test of its own; incremental equals full (a doc edit and a body edit repair one file, a removed function is a full run); 60 modules give the same edges and rows with one worker and several. Each rule red with it reverted (global fallback, self/static, parent, trait members, the folded-name gap, use aliases, method names without case, the bare-name method lookup, the namespace roots, code spans, the method-name guard, conditional declarations). Signed-off-by: Martin Vogel <[email protected]>
1 parent 196ca71 commit 7a321ca

10 files changed

Lines changed: 2438 additions & 3 deletions

File tree

‎Makefile.cbm‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -391,6 +391,7 @@ EXTRACTION_SRCS = \
391391
$(CBM_DIR)/doclink_rs.c \
392392
$(CBM_DIR)/doclink_perl.c \
393393
$(CBM_DIR)/doclink_ts.c \
394+
$(CBM_DIR)/doclink_php.c \
394395
$(CBM_DIR)/sql_values.c \
395396
$(CBM_DIR)/helpers.c \
396397
$(CBM_DIR)/cpp_branch_views.c \
@@ -522,6 +523,7 @@ PIPELINE_SRCS = \
522523
src/pipeline/doc_links_rs.c \
523524
src/pipeline/doc_links_perl.c \
524525
src/pipeline/doc_links_ts.c \
526+
src/pipeline/doc_links_php.c \
525527
src/pipeline/doc_links_msbuild.c \
526528
src/pipeline/pass_route_nodes.c \
527529
src/pipeline/pass_enrichment.c \
@@ -784,7 +786,7 @@ TEST_DISCOVER_SRCS = \
784786

785787
TEST_GRAPH_BUFFER_SRCS = tests/test_graph_buffer.c
786788

787-
TEST_PIPELINE_SRCS = tests/test_registry.c tests/test_pipeline.c tests/test_pipeline_conventions.c tests/test_pipeline_frozen.c tests/test_importance.c tests/test_cross_repo.c tests/test_fqn.c tests/test_route_canon.c tests/test_path_alias.c tests/test_configlink.c tests/test_doclinks.c tests/test_doc_mentions.c tests/test_doc_links_md.c tests/test_doc_links_pdf.c tests/test_doc_links_rst.c tests/test_doc_links_adoc.c tests/test_doc_mentions_go.c tests/test_doc_mentions_jvm.c tests/test_doc_mentions_rs.c tests/test_doc_mentions_perl.c tests/test_doc_mentions_ts.c tests/test_infrascan.c tests/test_worker_pool.c tests/test_parallel.c tests/test_index_resilience.c tests/test_index_format.c tests/test_call_reference_contract.c tests/repro/repro_call_scope_usages.c tests/repro/repro_call_argument_usages.c tests/repro/repro_reference_precision.c tests/repro/repro_lexical_binding_precision.c tests/repro/repro_call_argument_matrix_a.c tests/repro/repro_call_argument_matrix_b.c tests/repro/repro_call_node_behaviors.c tests/repro/repro_language_registry.c tests/repro/repro_call_node_manifest.c tests/repro/repro_lsp_ordered_signatures.c tests/repro/repro_lsp_ordered_local.c tests/repro/repro_ts_overload_return_chains.c tests/repro/repro_harness_cleanup.c tests/repro/repro_runner_filter.c
789+
TEST_PIPELINE_SRCS = tests/test_registry.c tests/test_pipeline.c tests/test_pipeline_conventions.c tests/test_pipeline_frozen.c tests/test_importance.c tests/test_cross_repo.c tests/test_fqn.c tests/test_route_canon.c tests/test_path_alias.c tests/test_configlink.c tests/test_doclinks.c tests/test_doc_mentions.c tests/test_doc_links_md.c tests/test_doc_links_pdf.c tests/test_doc_links_rst.c tests/test_doc_links_adoc.c tests/test_doc_mentions_go.c tests/test_doc_mentions_jvm.c tests/test_doc_mentions_rs.c tests/test_doc_mentions_perl.c tests/test_doc_mentions_ts.c tests/test_doc_mentions_php.c tests/test_infrascan.c tests/test_worker_pool.c tests/test_parallel.c tests/test_index_resilience.c tests/test_index_format.c tests/test_call_reference_contract.c tests/repro/repro_call_scope_usages.c tests/repro/repro_call_argument_usages.c tests/repro/repro_reference_precision.c tests/repro/repro_lexical_binding_precision.c tests/repro/repro_call_argument_matrix_a.c tests/repro/repro_call_argument_matrix_b.c tests/repro/repro_call_node_behaviors.c tests/repro/repro_language_registry.c tests/repro/repro_call_node_manifest.c tests/repro/repro_lsp_ordered_signatures.c tests/repro/repro_lsp_ordered_local.c tests/repro/repro_ts_overload_return_chains.c tests/repro/repro_harness_cleanup.c tests/repro/repro_runner_filter.c
788790

789791
TEST_WATCHER_SRCS = tests/test_watcher.c
790792

‎internal/cbm/doclink.c‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,11 @@ static const doclink_lang_t DOCLINK_LANGS[] = {
234234
.scan_scope = cbm_doclink_ts_scan_scope,
235235
.scope_tag = CBM_DOCLINK_TS_SCOPE_TAG,
236236
.portable_scope = cbm_doclink_ts_portable_scope},
237+
{.lang = CBM_LANG_PHP,
238+
.parse_doc = cbm_doclink_php_parse_doc,
239+
.scan_scope = cbm_doclink_php_scan_scope,
240+
.scope_tag = CBM_DOCLINK_PHP_SCOPE_TAG,
241+
.portable_scope = cbm_doclink_php_portable_scope},
237242
};
238243

239244
static const doclink_lang_t *doclink_lang(CBMLanguage lang) {

‎internal/cbm/doclink.h‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,8 @@
104104
X(CBM_DOCLINK_TS_LINK, CBM_LANG_TYPESCRIPT, "link", false, false, "MENTIONS") \
105105
X(CBM_DOCLINK_TS_LINKCODE, CBM_LANG_TYPESCRIPT, "linkcode", false, false, "MENTIONS") \
106106
X(CBM_DOCLINK_TS_SEE, CBM_LANG_TYPESCRIPT, "see", false, false, "MENTIONS") \
107+
/* php (doclink_php.c): PHPDoc @see and {@see}; held until their audit passes */ \
108+
X(CBM_DOCLINK_PHP_SEE, CBM_LANG_PHP, "see", false, false, "MENTIONS") \
107109
/* markdown (doclink_md.c): what a document's text names explicitly */ \
108110
X(CBM_DOCLINK_MD_LINK, CBM_LANG_MARKDOWN, "link", false, true, "MENTIONS") \
109111
X(CBM_DOCLINK_MD_PATH, CBM_LANG_MARKDOWN, "path", false, true, "MENTIONS") \
@@ -555,6 +557,40 @@ char *cbm_doclink_ts_portable_scope(const char *scope);
555557
* this length and the resolver reports it as unparseable. */
556558
enum { CBM_DOCLINK_TS_REF_MAX = 512 };
557559

560+
/* ── PHP (doclink_php.c) ───────────────────────────────────────────── */
561+
562+
void cbm_doclink_php_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,
563+
uint32_t doc_line);
564+
const char *cbm_doclink_php_scan_scope(CBMExtractCtx *ctx);
565+
char *cbm_doclink_php_portable_scope(const char *scope);
566+
567+
#define CBM_DOCLINK_PHP_SCOPE_TAG "php1"
568+
569+
/* The longest reference a PHP token keeps; a longer one is cut just past this
570+
* length and the resolver reports it as unparseable. */
571+
enum { CBM_DOCLINK_PHP_REF_MAX = 512 };
572+
573+
/* One `use` import of a PHP namespace block: kind 'c' (a class or namespace),
574+
* 'f' (a function), 'k' (a constant); the name without a leading backslash. */
575+
typedef struct {
576+
const char *alias;
577+
size_t alias_len;
578+
const char *name;
579+
size_t name_len;
580+
char kind;
581+
} cbm_doclink_php_use_t;
582+
583+
/* The fully qualified name (no leading backslash) of a type name `ref` (n
584+
* bytes) written in namespace `ns` (ns_len 0: the global one) under these
585+
* imports, as PHP resolves it: a leading backslash is taken as written,
586+
* `namespace\` stands for the current namespace, else the first segment is
587+
* replaced when it is the alias of a class import (compared without case),
588+
* else the namespace is put in front. Writes NUL-terminated into out (cap
589+
* bytes); returns the length, 0 when it does not fit. */
590+
size_t cbm_doclink_php_qualify(char *out, size_t cap, const char *ns, size_t ns_len,
591+
const cbm_doclink_php_use_t *uses, int nuses, const char *ref,
592+
size_t n);
593+
558594
/* ── Perl POD (doclink_perl.c) ─────────────────────────────────────── */
559595

560596
void cbm_doclink_perl_parse_doc(CBMExtractCtx *ctx, const CBMDefinition *def, const char *doc,

0 commit comments

Comments
 (0)