Každá položka, kterou crate exportuje, má svou stránku rustdoc na routě odvozené z její cesty a druhu, žádná stránka položky neexistuje bez své položky a modul přidaný do crate se stane povinnou stránkou bez úpravy jakéhokoli seznamu

Co to znamená

Publikovaná reference je vůči crate úplná: každá položka, kterou crate exportuje, má stránku, kterou jí rustdoc dává, na trase odvozené z cesty a druhu položky, a neexistuje stránka položky, kterou crate neexportuje. Modul přidaný do crate se stane stránkou, kterou kontrola vyžaduje, aniž kdo upravuje seznam, a odebraný modul si své stránky odnese.

Princip

majordomus quality rustdoc čte vykreslený strom proti quality::source::Inventory — crate čtený jako syntaktický strom, procházený od kořene tak, jak jej prochází překladač, což je totéž měření, jímž project.rust-public-api-quality crate drží. Z cesty a druhu každé exportované položky odvodí trasu, kterou používá rustdoc, a obě množiny porovná oběma směry: položka bez stránky je nález a stejně tak stránka položky bez položky. Tentýž průchod kontroluje, že strom byl sestaven z HEAD, že index knihovny nese její identitu, že aktiva indexu jsou přítomna, že interní odkazy se rozřeší a že žádná stránka nejmenuje cestu na stroji ani tajemství.

Skončí 0 při čistém stavu, 10 s jedním nálezem na porušení a 12, když není co posuzovat. Nikdy nehlásí úspěch nad prázdným stromem.

Jak to vidět

scripts/rust-check --doc
majordomus quality rustdoc                   # the counts it joined, then any finding
majordomus quality rustdoc --tree site/public/rustdoc
bash test/run.sh 490_rustdoc_new_module
cargo test --manifest-path apps/majordomus-cli/Cargo.toml quality::rustdoc

Co nepokrývá

Zda stojí za to dokumentaci položky číst, rozhoduje project.rust-public-api-quality a kontrola rust-quality; toto tvrzení se týká toho, že stránka existuje tam, kde má. Privátní položky se nedokumentují a nečeká se to. Konvence rout patří toolchainu připnutému v rust-toolchain.toml; změna, která ji mění, se zde zachytí jako nálezy a opraví se ve stejné změně.

Proč existuje

Reference je velká množina a svůdný způsob, jak velkou množinu kontrolovat, je seznam. Seznam modulů vedený pro referenci zastarává ve směru, který prochází: nový modul na něm není, takže jeho chybějící stránka nikdy není nález. Spojení stromu s vlastním inventářem crate znamená, že množina, kterou kontrola očekává, se pokaždé odvozuje z kódu. test/cases/490_rustdoc_new_module.sh přidá modul do testovacího crate a sleduje, jak se z něj stane povinná stránka.