Skip to content

Commit 78eace4

Browse files
committed
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 <martin.vogel.tech@gmail.com>
1 parent abf6558 commit 78eace4

5 files changed

Lines changed: 48 additions & 62 deletions

File tree

‎internal/cbm/doclink.h‎

Lines changed: 25 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -89,32 +89,33 @@
8989
X(CBM_DOCLINK_CS_SEEALSO, CBM_LANG_CSHARP, "seealso", false, true, "MENTIONS") \
9090
X(CBM_DOCLINK_CS_EXCEPTION, CBM_LANG_CSHARP, "exception", false, true, "MENTIONS") \
9191
X(CBM_DOCLINK_CS_INHERITDOC, CBM_LANG_CSHARP, "inheritdoc", false, true, "MENTIONS") \
92-
/* go (doclink_go.c): [Name] doc links; held until its held-out audit passes */ \
93-
X(CBM_DOCLINK_GO_DOC_LINK, CBM_LANG_GO, "doc_link", false, false, "MENTIONS") \
94-
/* java and kotlin (doclink_jvm.c): Javadoc and KDoc; held until their audit passes */ \
95-
X(CBM_DOCLINK_JAVA_LINK, CBM_LANG_JAVA, "link", false, false, "MENTIONS") \
96-
X(CBM_DOCLINK_JAVA_LINKPLAIN, CBM_LANG_JAVA, "linkplain", false, false, "MENTIONS") \
97-
X(CBM_DOCLINK_JAVA_SEE, CBM_LANG_JAVA, "see", false, false, "MENTIONS") \
98-
X(CBM_DOCLINK_JAVA_THROWS, CBM_LANG_JAVA, "throws", false, false, "MENTIONS") \
99-
X(CBM_DOCLINK_JAVA_VALUE, CBM_LANG_JAVA, "value", false, false, "MENTIONS") \
100-
X(CBM_DOCLINK_KT_KDOC_LINK, CBM_LANG_KOTLIN, "kdoc_link", false, false, "MENTIONS") \
101-
X(CBM_DOCLINK_KT_SEE, CBM_LANG_KOTLIN, "see", false, false, "MENTIONS") \
102-
X(CBM_DOCLINK_KT_THROWS, CBM_LANG_KOTLIN, "throws", false, false, "MENTIONS") \
103-
X(CBM_DOCLINK_KT_SAMPLE, CBM_LANG_KOTLIN, "sample", false, false, "MENTIONS") \
104-
/* rust (doclink_rs.c): intra-doc links; held until their audit passes */ \
105-
X(CBM_DOCLINK_RS_INTRA_DOC, CBM_LANG_RUST, "intra_doc", false, false, "MENTIONS") \
106-
X(CBM_DOCLINK_RS_LINK_DEF, CBM_LANG_RUST, "link_def", false, false, "MENTIONS") \
107-
/* perl (doclink_perl.c): POD L<> codes; held until their audit passes */ \
108-
X(CBM_DOCLINK_PERL_POD_L, CBM_LANG_PERL, "pod_L", false, false, "MENTIONS") \
109-
/* typescript and javascript (doclink_ts.c): JSDoc/TSDoc; held until their audit */ \
110-
X(CBM_DOCLINK_TS_LINK, CBM_LANG_TYPESCRIPT, "link", false, false, "MENTIONS") \
92+
/* go (doclink_go.c): [Name] doc links; held-out audit passed */ \
93+
X(CBM_DOCLINK_GO_DOC_LINK, CBM_LANG_GO, "doc_link", false, true, "MENTIONS") \
94+
/* java and kotlin (doclink_jvm.c): Javadoc and KDoc; held-out audit passed */ \
95+
X(CBM_DOCLINK_JAVA_LINK, CBM_LANG_JAVA, "link", false, true, "MENTIONS") \
96+
X(CBM_DOCLINK_JAVA_LINKPLAIN, CBM_LANG_JAVA, "linkplain", false, true, "MENTIONS") \
97+
X(CBM_DOCLINK_JAVA_SEE, CBM_LANG_JAVA, "see", false, true, "MENTIONS") \
98+
X(CBM_DOCLINK_JAVA_THROWS, CBM_LANG_JAVA, "throws", false, true, "MENTIONS") \
99+
X(CBM_DOCLINK_JAVA_VALUE, CBM_LANG_JAVA, "value", false, true, "MENTIONS") \
100+
X(CBM_DOCLINK_KT_KDOC_LINK, CBM_LANG_KOTLIN, "kdoc_link", false, true, "MENTIONS") \
101+
X(CBM_DOCLINK_KT_SEE, CBM_LANG_KOTLIN, "see", false, true, "MENTIONS") \
102+
X(CBM_DOCLINK_KT_THROWS, CBM_LANG_KOTLIN, "throws", false, true, "MENTIONS") \
103+
X(CBM_DOCLINK_KT_SAMPLE, CBM_LANG_KOTLIN, "sample", false, true, "MENTIONS") \
104+
/* rust (doclink_rs.c): intra-doc links; held-out audit passed */ \
105+
X(CBM_DOCLINK_RS_INTRA_DOC, CBM_LANG_RUST, "intra_doc", false, true, "MENTIONS") \
106+
X(CBM_DOCLINK_RS_LINK_DEF, CBM_LANG_RUST, "link_def", false, true, "MENTIONS") \
107+
/* perl (doclink_perl.c): POD L<> codes; held-out audit passed */ \
108+
X(CBM_DOCLINK_PERL_POD_L, CBM_LANG_PERL, "pod_L", false, true, "MENTIONS") \
109+
/* typescript and javascript (doclink_ts.c): JSDoc/TSDoc; {@link} passed its held-out */ \
110+
/* audit; {@linkcode} (10) and @see (18) had too few held-out links to pass: held */ \
111+
X(CBM_DOCLINK_TS_LINK, CBM_LANG_TYPESCRIPT, "link", false, true, "MENTIONS") \
111112
X(CBM_DOCLINK_TS_LINKCODE, CBM_LANG_TYPESCRIPT, "linkcode", false, false, "MENTIONS") \
112113
X(CBM_DOCLINK_TS_SEE, CBM_LANG_TYPESCRIPT, "see", false, false, "MENTIONS") \
113-
/* php (doclink_php.c): PHPDoc @see and {@see}; held until their audit passes */ \
114-
X(CBM_DOCLINK_PHP_SEE, CBM_LANG_PHP, "see", false, false, "MENTIONS") \
115-
/* c (doclink_c.c): Doxygen @ref and @see in .c and .h files; held until their audit */ \
116-
X(CBM_DOCLINK_C_REF, CBM_LANG_C, "doxygen_ref", false, false, "MENTIONS") \
117-
X(CBM_DOCLINK_C_SEE, CBM_LANG_C, "see", false, false, "MENTIONS") \
114+
/* php (doclink_php.c): PHPDoc @see and {@see}; held-out audit passed */ \
115+
X(CBM_DOCLINK_PHP_SEE, CBM_LANG_PHP, "see", false, true, "MENTIONS") \
116+
/* c (doclink_c.c): Doxygen @ref and @see in .c and .h files; held-out audit passed */ \
117+
X(CBM_DOCLINK_C_REF, CBM_LANG_C, "doxygen_ref", false, true, "MENTIONS") \
118+
X(CBM_DOCLINK_C_SEE, CBM_LANG_C, "see", false, true, "MENTIONS") \
118119
/* markdown (doclink_md.c): what a document's text names explicitly */ \
119120
X(CBM_DOCLINK_MD_LINK, CBM_LANG_MARKDOWN, "link", false, true, "MENTIONS") \
120121
X(CBM_DOCLINK_MD_PATH, CBM_LANG_MARKDOWN, "path", false, true, "MENTIONS") \

‎tests/test_doc_links_md.c‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -602,6 +602,18 @@ TEST(doc_links_md_ship_gate) {
602602
ASSERT_FALSE(cbm_doclink_syntax_ships(DM_HELD_FAMILIES[i]));
603603
}
604604
ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_MD_LINK));
605+
/* the doc-comment families whose held-out tiers passed (2026-10-11) */
606+
static const int passed[] = {
607+
CBM_DOCLINK_GO_DOC_LINK, CBM_DOCLINK_JAVA_LINK, CBM_DOCLINK_JAVA_LINKPLAIN,
608+
CBM_DOCLINK_JAVA_SEE, CBM_DOCLINK_JAVA_THROWS, CBM_DOCLINK_JAVA_VALUE,
609+
CBM_DOCLINK_KT_KDOC_LINK, CBM_DOCLINK_KT_SEE, CBM_DOCLINK_KT_THROWS,
610+
CBM_DOCLINK_KT_SAMPLE, CBM_DOCLINK_RS_INTRA_DOC, CBM_DOCLINK_RS_LINK_DEF,
611+
CBM_DOCLINK_PERL_POD_L, CBM_DOCLINK_TS_LINK, CBM_DOCLINK_PHP_SEE,
612+
CBM_DOCLINK_C_REF, CBM_DOCLINK_C_SEE,
613+
};
614+
for (size_t i = 0; i < sizeof(passed) / sizeof(passed[0]); i++) {
615+
ASSERT_TRUE(cbm_doclink_syntax_ships(passed[i]));
616+
}
605617
ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_RST_ROLE));
606618
ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_ADOC_INCLUDE));
607619
ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_RST_LITERALINCLUDE));

‎tests/test_doc_mentions_go.c‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -176,11 +176,11 @@ TEST(doc_mentions_go_tokens) {
176176
const CBMDocLinkFamily *f = cbm_doclink_family(CBM_DOCLINK_GO_DOC_LINK);
177177
ASSERT_NOT_NULL(f);
178178
ASSERT_EQ(f->lang, CBM_LANG_GO);
179-
/* held in production until its held-out audit passes; the suite ships it */
179+
/* ships in production: its held-out audit passed */
180180
cbm_doclink_test_reset_ships();
181181
bool ships_in_production = cbm_doclink_syntax_ships(CBM_DOCLINK_GO_DOC_LINK);
182182
dm_ship_held_families();
183-
ASSERT_FALSE(ships_in_production);
183+
ASSERT_TRUE(ships_in_production);
184184
ASSERT_TRUE(cbm_doclink_syntax_ships(CBM_DOCLINK_GO_DOC_LINK));
185185
PASS();
186186
}
@@ -1748,6 +1748,7 @@ TEST(doc_mentions_go_ship_gate) {
17481748
char db[512];
17491749
cbm_doclink_test_set_ships(CBM_DOCLINK_GO_DOC_LINK, false);
17501750
int rc = go_index_lookup(tmp, sizeof(tmp), db, sizeof(db));
1751+
cbm_doclink_test_reset_ships(); /* production gates again for the tests after this one */
17511752
dm_ship_held_families();
17521753
ASSERT_EQ(rc, 0);
17531754
/* a resolved doc link is a row with the gate's reason and no edge */

‎tests/test_doc_mentions_helpers.h‎

Lines changed: 6 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -430,40 +430,12 @@ static inline int dm_reason_lines(const char *db, const char *block) {
430430
* so it is the resolution an audit would ship; doc_links_md_ship_gate tests
431431
* the production gate itself. */
432432
static const int DM_HELD_FAMILIES[] = {
433-
CBM_DOCLINK_MD_BARE_PATH,
434-
CBM_DOCLINK_MD_SUPERSEDES_PROSE,
435-
CBM_DOCLINK_RST_INCLUDE,
436-
CBM_DOCLINK_RST_KERNEL_DOC,
437-
CBM_DOCLINK_ADOC_ATTRIBUTE,
438-
CBM_DOCLINK_ADOC_CODE_PATH,
439-
CBM_DOCLINK_ADOC_CODE_NAME,
440-
CBM_DOCLINK_GO_DOC_LINK,
441-
CBM_DOCLINK_JAVA_LINK,
442-
CBM_DOCLINK_JAVA_LINKPLAIN,
443-
CBM_DOCLINK_JAVA_SEE,
444-
CBM_DOCLINK_JAVA_THROWS,
445-
CBM_DOCLINK_JAVA_VALUE,
446-
CBM_DOCLINK_KT_KDOC_LINK,
447-
CBM_DOCLINK_KT_SEE,
448-
CBM_DOCLINK_KT_THROWS,
449-
CBM_DOCLINK_KT_SAMPLE,
450-
CBM_DOCLINK_RS_INTRA_DOC,
451-
CBM_DOCLINK_RS_LINK_DEF,
452-
CBM_DOCLINK_PERL_POD_L,
453-
CBM_DOCLINK_TS_LINK,
454-
CBM_DOCLINK_TS_LINKCODE,
455-
CBM_DOCLINK_TS_SEE,
456-
CBM_DOCLINK_PHP_SEE,
457-
CBM_DOCLINK_C_REF,
458-
CBM_DOCLINK_C_SEE,
459-
CBM_DOCLINK_DG_MERMAID_CLICK,
460-
CBM_DOCLINK_DG_PLANTUML_URL,
461-
CBM_DOCLINK_DG_PLANTUML_INCLUDE,
462-
CBM_DOCLINK_DG_DRAWIO_LINK,
463-
CBM_DOCLINK_DG_EXCALIDRAW_LINK,
464-
CBM_DOCLINK_DG_DOT_URL,
465-
CBM_DOCLINK_DG_D2_LINK,
466-
CBM_DOCLINK_OPENAPI_OPERATION_ID,
433+
CBM_DOCLINK_MD_BARE_PATH, CBM_DOCLINK_MD_SUPERSEDES_PROSE, CBM_DOCLINK_RST_INCLUDE,
434+
CBM_DOCLINK_RST_KERNEL_DOC, CBM_DOCLINK_ADOC_ATTRIBUTE, CBM_DOCLINK_ADOC_CODE_PATH,
435+
CBM_DOCLINK_ADOC_CODE_NAME, CBM_DOCLINK_TS_LINKCODE, CBM_DOCLINK_TS_SEE,
436+
CBM_DOCLINK_DG_MERMAID_CLICK, CBM_DOCLINK_DG_PLANTUML_URL, CBM_DOCLINK_DG_PLANTUML_INCLUDE,
437+
CBM_DOCLINK_DG_DRAWIO_LINK, CBM_DOCLINK_DG_EXCALIDRAW_LINK, CBM_DOCLINK_DG_DOT_URL,
438+
CBM_DOCLINK_DG_D2_LINK, CBM_DOCLINK_OPENAPI_OPERATION_ID,
467439
};
468440

469441
static inline void dm_ship_held_families(void) {

‎tests/test_doc_mentions_jvm.c‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2556,14 +2556,14 @@ TEST(doc_mentions_jvm_family_names) {
25562556
ASSERT_STR_EQ(cbm_doclink_syntax_name(families[i].syntax), families[i].name);
25572557
ASSERT_FALSE(cbm_doclink_syntax_is_external(families[i].syntax));
25582558
}
2559-
/* held in production until their held-out audit passes; the suite ships them */
2559+
/* all ship in production: their held-out audit passed */
25602560
cbm_doclink_test_reset_ships();
25612561
int shipping_in_production = 0;
25622562
for (size_t i = 0; i < sizeof(families) / sizeof(families[0]); i++) {
25632563
shipping_in_production += cbm_doclink_syntax_ships(families[i].syntax) ? 1 : 0;
25642564
}
25652565
dm_ship_held_families();
2566-
ASSERT_EQ(shipping_in_production, 0);
2566+
ASSERT_EQ(shipping_in_production, (int)(sizeof(families) / sizeof(families[0])));
25672567
for (size_t i = 0; i < sizeof(families) / sizeof(families[0]); i++) {
25682568
ASSERT_TRUE(cbm_doclink_syntax_ships(families[i].syntax));
25692569
}

0 commit comments

Comments
 (0)