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: ship the doc-comment families that passed their held-out audit

Martin Vogel78eace4fd363
diff --git a/internal/cbm/doclink.h b/internal/cbm/doclink.h
index 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.c
index 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.c
index 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.h
index 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.c
index 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));
}