Module policy 

What the repository demands of an exported item, and what counts as having met it.

The two questions

Does this item owe an example? — ExampleRequirement::of answers from the item’s kind and shape alone. A module, a type, a function, a method and an exported macro owe one. A field, a variant, a constant, a static, a type alias, an associated item and a trivial accessor do not, each for a reason the report prints: an example of a value is an example of whatever uses it, and a rule that demands one buys the placeholder this module exists to refuse. The classification is derived, never declared, so there is no exemption list for anyone to add a line to.

Does this example count? — Verdict::of answers with the signals a machine can check: the block is compiled by the toolchain, it names the item it documents, and it asserts something that is not true of every program. That is deliberately not a judgement about prose. It is the smallest set of tests that makes the obvious ways of satisfying a counter fail.

What it refuses

use majordomus_cli::quality::policy::Verdict;
use majordomus_cli::quality::source::Example;

// the classic: the item named, a fence, and an assertion true of every program
let placeholder = Example::parse("", &["let _: Foo;".into(), "assert!(true);".into()]);
assert_eq!(Verdict::of(&placeholder, "Foo"), Verdict::Placeholder);

// compiled by nobody
let ignored = Example::parse("ignore", &["Foo::new().run();".into()]);
assert_eq!(Verdict::of(&ignored, "Foo"), Verdict::NotExecutable);

// runs, asserts, and never mentions what it is documenting
let elsewhere = Example::parse("", &["let n = 2 + 2;".into(), "assert_eq!(n, 4);".into()]);
assert_eq!(Verdict::of(&elsewhere, "Foo"), Verdict::DoesNotNameSubject);

// and what it accepts
let real = Example::parse("", &["assert_eq!(Foo::new().len(), 0);".into()]);
assert_eq!(Verdict::of(&real, "Foo"), Verdict::Counts);

Enums

ExampleRequirement

Whether an item owes an executable example, and when it does not, why not.

Verdict

What one fenced block is worth as evidence about one item.

Constants

MIN_MODULE_PROSE_WORDS

The fewest words a module’s //! header must carry. A module is a conceptual boundary and explaining one costs more than a sentence.

MIN_PROSE_WORDS

The fewest words of prose the documentation of a behaviour-bearing exported item must carry, below which it is repeating the signature.

Functions

asserts_something

Does the code assert anything that could be false?

names

Does the code name the subject as an identifier, rather than inside a longer word?