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.
C aiderastclaude-codecode-analysiscode-intelligencecodexcursorcypherdeveloper-toolsgemini-cligraph-visualizationkilocodeknowledge-graphmcpmcp-servermodel-context-protocolopencodesqlitetree-sitterwindsurf
doc-links: ship the doc-comment families that passed their held-out audit
Martin Vogel78eace4fd363
diff --git a/internal/cbm/doclink.h b/internal/cbm/doclink.hindex 0ccdcec20..c645d7346 100644--- a/internal/cbm/doclink.h+++ b/internal/cbm/doclink.h@@ -89,32 +89,33 @@X(CBM_DOCLINK_CS_SEEALSO, CBM_LANG_CSHARP, "seealso", false, true, "MENTIONS") \X(CBM_DOCLINK_CS_EXCEPTION, CBM_LANG_CSHARP, "exception", false, true, "MENTIONS") \X(CBM_DOCLINK_CS_INHERITDOC, CBM_LANG_CSHARP, "inheritdoc", false, true, "MENTIONS") \- /* go (doclink_go.c): [Name] doc links; held until its held-out audit passes */ \- X(CBM_DOCLINK_GO_DOC_LINK, CBM_LANG_GO, "doc_link", false, false, "MENTIONS") \- /* java and kotlin (doclink_jvm.c): Javadoc and KDoc; held until their audit passes */ \- X(CBM_DOCLINK_JAVA_LINK, CBM_LANG_JAVA, "link", false, false, "MENTIONS") \- X(CBM_DOCLINK_JAVA_LINKPLAIN, CBM_LANG_JAVA, "linkplain", false, false, "MENTIONS") \- X(CBM_DOCLINK_JAVA_SEE, CBM_LANG_JAVA, "see", false, false, "MENTIONS") \- X(CBM_DOCLINK_JAVA_THROWS, CBM_LANG_JAVA, "throws", false, false, "MENTIONS") \- X(CBM_DOCLINK_JAVA_VALUE, CBM_LANG_JAVA, "value", false, false, "MENTIONS") \- X(CBM_DOCLINK_KT_KDOC_LINK, CBM_LANG_KOTLIN, "kdoc_link", false, false, "MENTIONS") \- X(CBM_DOCLINK_KT_SEE, CBM_LANG_KOTLIN, "see", false, false, "MENTIONS") \- X(CBM_DOCLINK_KT_THROWS, CBM_LANG_KOTLIN, "throws", false, false, "MENTIONS") \- X(CBM_DOCLINK_KT_SAMPLE, CBM_LANG_KOTLIN, "sample", false, false, "MENTIONS") \- /* rust (doclink_rs.c): intra-doc links; held until their audit passes */ \- X(CBM_DOCLINK_RS_INTRA_DOC, CBM_LANG_RUST, "intra_doc", false, false, "MENTIONS") \- X(CBM_DOCLINK_RS_LINK_DEF, CBM_LANG_RUST, "link_def", false, false, "MENTIONS") \- /* perl (doclink_perl.c): POD L<> codes; held until their audit passes */ \- X(CBM_DOCLINK_PERL_POD_L, CBM_LANG_PERL, "pod_L", false, false, "MENTIONS") \- /* typescript and javascript (doclink_ts.c): JSDoc/TSDoc; held until their audit */ \- X(CBM_DOCLINK_TS_LINK, CBM_LANG_TYPESCRIPT, "link", false, false, "MENTIONS") \+ /* go (doclink_go.c): [Name] doc links; held-out audit passed */ \+ X(CBM_DOCLINK_GO_DOC_LINK, CBM_LANG_GO, "doc_link", false, true, "MENTIONS") \+ /* java and kotlin (doclink_jvm.c): Javadoc and KDoc; held-out audit passed */ \+ X(CBM_DOCLINK_JAVA_LINK, CBM_LANG_JAVA, "link", false, true, "MENTIONS") \+ X(CBM_DOCLINK_JAVA_LINKPLAIN, CBM_LANG_JAVA, "linkplain", false, true, "MENTIONS") \+ X(CBM_DOCLINK_JAVA_SEE, CBM_LANG_JAVA, "see", false, true, "MENTIONS") \+ X(CBM_DOCLINK_JAVA_THROWS, CBM_LANG_JAVA, "throws", false, true, "MENTIONS") \+ X(CBM_DOCLINK_JAVA_VALUE, CBM_LANG_JAVA, "value", false, true, "MENTIONS") \+ X(CBM_DOCLINK_KT_KDOC_LINK, CBM_LANG_KOTLIN, "kdoc_link", false, true, "MENTIONS") \+ X(CBM_DOCLINK_KT_SEE, CBM_LANG_KOTLIN, "see", false, true, "MENTIONS") \+ X(CBM_DOCLINK_KT_THROWS, CBM_LANG_KOTLIN, "throws", false, true, "MENTIONS") \+ X(CBM_DOCLINK_KT_SAMPLE, CBM_LANG_KOTLIN, "sample", false, true, "MENTIONS") \+ /* rust (doclink_rs.c): intra-doc links; held-out audit passed */ \+ X(CBM_DOCLINK_RS_INTRA_DOC, CBM_LANG_RUST, "intra_doc", false, true, "MENTIONS") \+ X(CBM_DOCLINK_RS_LINK_DEF, CBM_LANG_RUST, "link_def", false, true, "MENTIONS") \+ /* perl (doclink_perl.c): POD L<> codes; held-out audit passed */ \+ X(CBM_DOCLINK_PERL_POD_L, CBM_LANG_PERL, "pod_L", false, true, "MENTIONS") \+ /* typescript and javascript (doclink_ts.c): JSDoc/TSDoc; {@link} passed its held-out */ \+ /* audit; {@linkcode} (10) and @see (18) had too few held-out links to pass: held */ \+ X(CBM_DOCLINK_TS_LINK, CBM_LANG_TYPESCRIPT, "link", false, true, "MENTIONS") \X(CBM_DOCLINK_TS_LINKCODE, CBM_LANG_TYPESCRIPT, "linkcode", false, false, "MENTIONS") \X(CBM_DOCLINK_TS_SEE, CBM_LANG_TYPESCRIPT, "see", false, false, "MENTIONS") \- /* php (doclink_php.c): PHPDoc @see and {@see}; held until their audit passes */ \- X(CBM_DOCLINK_PHP_SEE, CBM_LANG_PHP, "see", false, false, "MENTIONS") \- /* c (doclink_c.c): Doxygen @ref and @see in .c and .h files; held until their audit */ \- X(CBM_DOCLINK_C_REF, CBM_LANG_C, "doxygen_ref", false, false, "MENTIONS") \- X(CBM_DOCLINK_C_SEE, CBM_LANG_C, "see", false, false, "MENTIONS") \+ /* php (doclink_php.c): PHPDoc @see and {@see}; held-out audit passed */ \+ X(CBM_DOCLINK_PHP_SEE, CBM_LANG_PHP, "see", false, true, "MENTIONS") \+ /* c (doclink_c.c): Doxygen @ref and @see in .c and .h files; held-out audit passed */ \+ X(CBM_DOCLINK_C_REF, CBM_LANG_C, "doxygen_ref", false, true, "MENTIONS") \+ X(CBM_DOCLINK_C_SEE, CBM_LANG_C, "see", false, true, "MENTIONS") \/* markdown (doclink_md.c): what a document's text names explicitly */ \X(CBM_DOCLINK_MD_LINK, CBM_LANG_MARKDOWN, "link", false, true, "MENTIONS") \X(CBM_DOCLINK_MD_PATH, CBM_LANG_MARKDOWN, "path", false, true, "MENTIONS") \diff --git a/tests/test_doc_links_md.c b/tests/test_doc_links_md.cindex 2b66e63bd..21e74f37e 100644--- a/tests/test_doc_links_md.c+++ b/tests/test_doc_links_md.c@@ -602,6 +602,18 @@ TEST(doc_links_md_ship_gate) {ASSERT_FALSE(cbm_doclink_syntax_ships(DM_HELD_FAMILIES[i]));}ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_MD_LINK));+ /* the doc-comment families whose held-out tiers passed (2026-10-11) */+ static const int passed[] = {+ CBM_DOCLINK_GO_DOC_LINK, CBM_DOCLINK_JAVA_LINK, CBM_DOCLINK_JAVA_LINKPLAIN,+ CBM_DOCLINK_JAVA_SEE, CBM_DOCLINK_JAVA_THROWS, CBM_DOCLINK_JAVA_VALUE,+ CBM_DOCLINK_KT_KDOC_LINK, CBM_DOCLINK_KT_SEE, CBM_DOCLINK_KT_THROWS,+ CBM_DOCLINK_KT_SAMPLE, CBM_DOCLINK_RS_INTRA_DOC, CBM_DOCLINK_RS_LINK_DEF,+ CBM_DOCLINK_PERL_POD_L, CBM_DOCLINK_TS_LINK, CBM_DOCLINK_PHP_SEE,+ CBM_DOCLINK_C_REF, CBM_DOCLINK_C_SEE,+ };+ for (size_t i = 0; i < sizeof(passed) / sizeof(passed[0]); i++) {+ ASSERT_TRUE(cbm_doclink_syntax_ships(passed[i]));+ }ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_RST_ROLE));ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_ADOC_INCLUDE));ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_RST_LITERALINCLUDE));diff --git a/tests/test_doc_mentions_go.c b/tests/test_doc_mentions_go.cindex f3d9b58b5..1f81030db 100644--- a/tests/test_doc_mentions_go.c+++ b/tests/test_doc_mentions_go.c@@ -176,11 +176,11 @@ TEST(doc_mentions_go_tokens) {const CBMDocLinkFamily *f = cbm_doclink_family(CBM_DOCLINK_GO_DOC_LINK);ASSERT_NOT_NULL(f);ASSERT_EQ(f->lang, CBM_LANG_GO);- /* held in production until its held-out audit passes; the suite ships it */+ /* ships in production: its held-out audit passed */cbm_doclink_test_reset_ships();bool ships_in_production = cbm_doclink_syntax_ships(CBM_DOCLINK_GO_DOC_LINK);dm_ship_held_families();- ASSERT_FALSE(ships_in_production);+ ASSERT_TRUE(ships_in_production);ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_GO_DOC_LINK));PASS();}@@ -1748,6 +1748,7 @@ TEST(doc_mentions_go_ship_gate) {char db[512];cbm_doclink_test_set_ships(CBM_DOCLINK_GO_DOC_LINK, false);int rc = go_index_lookup(tmp, sizeof(tmp), db, sizeof(db));+ cbm_doclink_test_reset_ships(); /* production gates again for the tests after this one */dm_ship_held_families();ASSERT_EQ(rc, 0);/* a resolved doc link is a row with the gate's reason and no edge */diff --git a/tests/test_doc_mentions_helpers.h b/tests/test_doc_mentions_helpers.hindex 778796393..7fc75e1ad 100644--- a/tests/test_doc_mentions_helpers.h+++ b/tests/test_doc_mentions_helpers.h@@ -430,40 +430,12 @@ static inline int dm_reason_lines(const char *db, const char *block) {* so it is the resolution an audit would ship; doc_links_md_ship_gate tests* the production gate itself. */static const int DM_HELD_FAMILIES[] = {- CBM_DOCLINK_MD_BARE_PATH,- CBM_DOCLINK_MD_SUPERSEDES_PROSE,- CBM_DOCLINK_RST_INCLUDE,- CBM_DOCLINK_RST_KERNEL_DOC,- CBM_DOCLINK_ADOC_ATTRIBUTE,- CBM_DOCLINK_ADOC_CODE_PATH,- CBM_DOCLINK_ADOC_CODE_NAME,- CBM_DOCLINK_GO_DOC_LINK,- CBM_DOCLINK_JAVA_LINK,- CBM_DOCLINK_JAVA_LINKPLAIN,- CBM_DOCLINK_JAVA_SEE,- CBM_DOCLINK_JAVA_THROWS,- CBM_DOCLINK_JAVA_VALUE,- CBM_DOCLINK_KT_KDOC_LINK,- CBM_DOCLINK_KT_SEE,- CBM_DOCLINK_KT_THROWS,- CBM_DOCLINK_KT_SAMPLE,- CBM_DOCLINK_RS_INTRA_DOC,- CBM_DOCLINK_RS_LINK_DEF,- CBM_DOCLINK_PERL_POD_L,- CBM_DOCLINK_TS_LINK,- CBM_DOCLINK_TS_LINKCODE,- CBM_DOCLINK_TS_SEE,- CBM_DOCLINK_PHP_SEE,- CBM_DOCLINK_C_REF,- CBM_DOCLINK_C_SEE,- CBM_DOCLINK_DG_MERMAID_CLICK,- CBM_DOCLINK_DG_PLANTUML_URL,- CBM_DOCLINK_DG_PLANTUML_INCLUDE,- CBM_DOCLINK_DG_DRAWIO_LINK,- CBM_DOCLINK_DG_EXCALIDRAW_LINK,- CBM_DOCLINK_DG_DOT_URL,- CBM_DOCLINK_DG_D2_LINK,- CBM_DOCLINK_OPENAPI_OPERATION_ID,+ CBM_DOCLINK_MD_BARE_PATH, CBM_DOCLINK_MD_SUPERSEDES_PROSE, CBM_DOCLINK_RST_INCLUDE,+ CBM_DOCLINK_RST_KERNEL_DOC, CBM_DOCLINK_ADOC_ATTRIBUTE, CBM_DOCLINK_ADOC_CODE_PATH,+ CBM_DOCLINK_ADOC_CODE_NAME, CBM_DOCLINK_TS_LINKCODE, CBM_DOCLINK_TS_SEE,+ CBM_DOCLINK_DG_MERMAID_CLICK, CBM_DOCLINK_DG_PLANTUML_URL, CBM_DOCLINK_DG_PLANTUML_INCLUDE,+ CBM_DOCLINK_DG_DRAWIO_LINK, CBM_DOCLINK_DG_EXCALIDRAW_LINK, CBM_DOCLINK_DG_DOT_URL,+ CBM_DOCLINK_DG_D2_LINK, CBM_DOCLINK_OPENAPI_OPERATION_ID,};static inline void dm_ship_held_families(void) {diff --git a/tests/test_doc_mentions_jvm.c b/tests/test_doc_mentions_jvm.cindex 31602e942..baa713001 100644--- a/tests/test_doc_mentions_jvm.c+++ b/tests/test_doc_mentions_jvm.c@@ -2556,14 +2556,14 @@ TEST(doc_mentions_jvm_family_names) {ASSERT_STR_EQ(cbm_doclink_syntax_name(families[i].syntax), families[i].name);ASSERT_FALSE(cbm_doclink_syntax_is_external(families[i].syntax));}- /* held in production until their held-out audit passes; the suite ships them */+ /* all ship in production: their held-out audit passed */cbm_doclink_test_reset_ships();int shipping_in_production = 0;for (size_t i = 0; i < sizeof(families) / sizeof(families[0]); i++) {shipping_in_production += cbm_doclink_syntax_ships(families[i].syntax) ? 1 : 0;}dm_ship_held_families();- ASSERT_EQ(shipping_in_production, 0);+ ASSERT_EQ(shipping_in_production, (int)(sizeof(families) / sizeof(families[0])));for (size_t i = 0; i < sizeof(families) / sizeof(families[0]); i++) {ASSERT_TRUE(cbm_doclink_syntax_ships(families[i].syntax));}