72 lines
2.6 KiB
Rust
72 lines
2.6 KiB
Rust
//! The harvested widget summaries must stay accurate and stay present.
|
|
//!
|
|
//! 147 of 197 widget structs carried a doc comment that reached no user: the trait has no
|
|
//! description, the inspector shows ports and parameters, the site's reference is a table
|
|
//! of ids. The text existed and had no path out.
|
|
use flowrs_core::graph::widget::WidgetRegistry;
|
|
use flowrs_core::graph::widget_docs::{WIDGET_DOCS, describe};
|
|
|
|
#[test]
|
|
fn every_summary_belongs_to_a_widget_that_exists() {
|
|
// A summary for a widget that has been renamed or removed is documentation pointing
|
|
// at nothing, and the table is generated — so a stale entry means the generator was
|
|
// not re-run.
|
|
let reg = WidgetRegistry::with_builtins();
|
|
let orphans: Vec<&str> = WIDGET_DOCS
|
|
.iter()
|
|
.map(|(id, _)| *id)
|
|
.filter(|id| reg.get(id).is_none())
|
|
.collect();
|
|
assert!(
|
|
orphans.is_empty(),
|
|
"{} summaries describe widgets that no longer exist — re-run \
|
|
tools/harvest_widget_docs.py:\n {}",
|
|
orphans.len(),
|
|
orphans.join("\n ")
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn most_widgets_are_documented_and_the_count_does_not_slip() {
|
|
let reg = WidgetRegistry::with_builtins();
|
|
let total = reg.all().len();
|
|
let documented = reg
|
|
.all()
|
|
.iter()
|
|
.filter(|w| describe(&w.id()).is_some())
|
|
.count();
|
|
|
|
// A ratchet, not a target. Adding a widget without a doc comment is allowed — writing
|
|
// one later is fine — but the proportion should not quietly fall.
|
|
const KNOWN_DOCUMENTED: usize = 266;
|
|
assert!(
|
|
documented >= KNOWN_DOCUMENTED,
|
|
"widget documentation went backwards: {documented} of {total} documented, was \
|
|
{KNOWN_DOCUMENTED}. A widget lost its doc comment, or the generator needs re-running."
|
|
);
|
|
assert!(
|
|
documented <= KNOWN_DOCUMENTED,
|
|
"good news: {documented} of {total} widgets are documented, up from \
|
|
{KNOWN_DOCUMENTED}. Raise KNOWN_DOCUMENTED to {documented} to hold the gain."
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_summary_says_something() {
|
|
// Guards the generator's own failure mode: taking a truncated or empty first line and
|
|
// shipping "Fft." as documentation.
|
|
for (id, doc) in WIDGET_DOCS {
|
|
assert!(
|
|
doc.len() >= 25,
|
|
"{id}: summary too short to be useful: {doc:?}"
|
|
);
|
|
assert!(
|
|
doc.ends_with('.') || doc.ends_with('!') || doc.ends_with('?'),
|
|
"{id}: summary looks truncated: {doc:?}"
|
|
);
|
|
assert!(
|
|
!doc.contains("**"),
|
|
"{id}: markdown leaked into the summary"
|
|
);
|
|
}
|
|
}
|