From 78eace4fd3631485b8784796b5e0ee4de143a105 Mon Sep 17 00:00:00 2001 From: Martin Vogel Date: Sun, 11 Oct 2026 12:43:35 +0200 Subject: [PATCH] doc-links: ship the doc-comment families that passed their held-out audit The held-out audit of the eight new languages is scored. Each tier is a language and a reference form, read on a sample of 150 links (census below 150) from repositories never used to build or tune the resolvers. Three blind reading rounds; bar: Wilson 95% lower bound >= 0.90 and point >= 0.95. tier population judged correct Wilson low go doc_link 5980 150 150 0.975 java link 23934 150 150 0.975 java linkplain 1372 150 150 0.975 java see 7711 150 150 0.975 java throws 650 150 150 0.975 java value 79 79 79 0.954 kotlin kdoc_link 3888 150 150 0.975 kotlin sample 279 150 150 0.975 kotlin see 369 150 150 0.975 kotlin throws 73 73 73 0.950 rust intra_doc 14119 150 149 0.963 rust link_def 1491 150 150 0.975 perl pod_L 2255 150 150 0.975 ts/js link 1222 150 150 0.975 php see 5171 150 150 0.975 c doxygen_ref 463 150 150 0.975 c see 509 150 145 0.924 These 17 families now ship: a resolved reference is a MENTIONS edge. TS/JS {@linkcode} (10 held-out links) and @see (18) were all judged correct, but are too few to reach the bar; they stay held, as do the diagram and OpenAPI link families (3 links on 21 held-out repositories). The Go ship-gate test turned its family off and restored only the held families afterwards; with Go shipping it left Go off for the tests that follow it. It restores the production gates first now. Signed-off-by: Martin Vogel --- internal/cbm/doclink.h | 49 ++++++++++++++++--------------- tests/test_doc_links_md.c | 12 ++++++++ tests/test_doc_mentions_go.c | 5 ++-- tests/test_doc_mentions_helpers.h | 40 ++++--------------------- tests/test_doc_mentions_jvm.c | 4 +-- 5 files changed, 48 insertions(+), 62 deletions(-) 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)); }