docs: add lots of internal docs (#199)

Author: ErichDonGubler

moz-webgpu-cts/src/file_spec.rs

@@ -1,3 +1,5 @@
+//! Contains [`FileSpec`]s: an abstraction for consistently handling file paths and globs from [the CLI](crate::main).
+
 use std::{fmt::Display, path::PathBuf};
 
 use miette::Report;

moz-webgpu-cts/src/process_reports.rs

@@ -1,3 +1,5 @@
+//! Implementation details for [`crate::process_reports()`].
+
 use std::{
     collections::BTreeMap,
     fmt::{Debug, Display},

moz-webgpu-cts/src/report.rs

@@ -1,17 +1,23 @@
+//! Data representation of WPT test reports. The conceptual entry point of this module is the
+//! [`ExecutionReport`] API.
+
 use serde::{
     de::{Deserializer, Error},
     Deserialize,
 };
 
 use crate::metadata::{BuildProfile, Platform, SubtestOutcome, TestOutcome};
 
+/// A `wptreport.json` file emitted by `wptrunner` and parsed by `moz-webgpu-cts` (which means it
+/// adheres to the strict subset that `moz-webgpu-cts` supports).
 #[derive(Debug, Deserialize)]
 pub(crate) struct ExecutionReport {
     pub run_info: RunInfo,
     #[serde(rename = "results")]
     pub entries: Vec<TestExecutionEntry>,
 }
 
+/// An [`ExecutionReport::run_info`].
 #[derive(Debug)]
 pub(crate) struct RunInfo {
     pub platform: Platform,
@@ -64,6 +70,7 @@ impl<'de> Deserialize<'de> for RunInfo {
     }
 }
 
+/// An entry in [`ExecutionReport::entries`].
 #[derive(Debug, Deserialize)]
 pub(crate) struct TestExecutionEntry {
     #[serde(rename = "test")]
@@ -72,6 +79,7 @@ pub(crate) struct TestExecutionEntry {
     pub result: TestExecutionResult,
 }
 
+/// A [`TestExecutionEntry::result`].
 #[derive(Debug, Deserialize)]
 #[serde(untagged)]
 pub(crate) enum TestExecutionResult {
@@ -86,6 +94,7 @@ pub(crate) enum TestExecutionResult {
     },
 }
 
+/// A subtest entry in [`TestExecutionResult`].
 #[derive(Debug, Deserialize)]
 pub(crate) struct SubtestExecutionResult {
     #[serde(rename = "name")]

moz-webgpu-cts/src/wpt.rs

@@ -1,2 +1,4 @@
+//! Important primitives for working with [Web Platform Test] metadata.
+
 pub(crate) mod metadata;
 pub(crate) mod path;

moz-webgpu-cts/src/wpt/metadata.rs

@@ -1,3 +1,6 @@
+//! `moz-webgpu-cts`' custom subset of WPT metadata. The conceptual entry point of this module is
+//! the [`File`] API.
+
 use std::{
     collections::BTreeMap,
     fmt::{self, Display, Formatter},
@@ -601,6 +604,10 @@ fn format_file_properties(props: &FileProps) -> impl Display + '_ {
     })
 }
 
+/// A `implementation-status` property value; see also the `implementation-status` entry in [WPT
+/// upstream documentation].
+///
+/// [WPT upstream]: https://web-platform-tests.org/tools/wptrunner/docs/expectation.html#web-platform-tests-metadata
 #[derive(Debug, Default, EnumSetType, Serialize, ValueEnum)]
 pub enum ImplementationStatus {
     /// Indicates that functionality governing test(s) is implemented or currently being
@@ -906,13 +913,23 @@ where
     })
 }
 
+/// The subset of WPT run environments can be handled by `moz-webgpu-cts`. Part of
+/// [`Applicability`].
+///
+/// This is essentially the set of OSes, software versions, and hardware that Firefox's WebGPU team
+/// uses in CI for WebGPU. When that changes, this changes accordingly.
 #[derive(Clone, Copy, Debug, Enum, Exhaust, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
 pub enum Platform {
     Windows,
     Linux,
     MacOs,
 }
 
+/// The subset of browser build profiles can be handled by `moz-webgpu-cts`. Part of
+/// [`Applicability`].
+///
+/// This is essentially the set of profiles that Firefox's WebGPU team uses in CI for WebGPU. When
+/// that changes, this changes accordingly.
 #[derive(Clone, Copy, Debug, Enum, Exhaust, Eq, Hash, Ord, PartialEq, PartialOrd, Serialize)]
 pub enum BuildProfile {
     Debug,
@@ -1020,6 +1037,10 @@ where
     }
 }
 
+/// The strict subset of WPT property conditionals that can be handled with `moz-webgpu-cts`.
+///
+/// The entire set of possible values here should be small enough that, when it is a key like in
+/// [`ExpandedPropertyValue`], significant performance gains are possible.
 #[derive(Clone, Debug, Default)]
 pub struct Applicability {
     pub platform: Option<Platform>,

moz-webgpu-cts/src/wpt/metadata/maybe_collapsed.rs

@@ -1,3 +1,5 @@
+//! A module holding the [`MaybeCollapsed`] abstraction.
+
 use std::fmt::Debug;
 
 /// Similar to the ubiquitous `enum Either`, but with the implication that `Collapsed` values are

moz-webgpu-cts/src/wpt/metadata/properties.rs

@@ -1,3 +1,5 @@
+//! WPT properties' value representation for `moz-webgpu-cts`.
+
 use std::{
     collections::BTreeMap,
     fmt::{self, Debug, Display, Formatter},
@@ -16,11 +18,16 @@ pub use self::disabled_string::DisabledString;
 
 mod disabled_string;
 
-/// A non-empty set of expected outcomes in a [`Test`] or [`Subtest`].
+/// A non-empty set of expected outcomes in a [`Test`] or [`Subtest`]. See also the `expected`
+/// entry in [WPT upstream documentation].
+///
+/// [WPT upstream]: https://web-platform-tests.org/tools/wptrunner/docs/expectation.html#web-platform-tests-metadata
 ///
 /// The default expected test outcome is a "good" outcome, where testing passes. The `Out` type
 /// parameter should return this value in its implementation of `Default`.
 ///
+/// Internally, this type is represented as a computationally efficient bitset.
+///
 /// [`Test`]: crate::metadata::Test
 /// [`Subtest`]: crate::metadata::Subtest
 #[derive(Clone, Copy, Serialize)]

moz-webgpu-cts/src/wpt/metadata/properties/disabled_string.rs

@@ -5,6 +5,9 @@ use std::{
 
 use serde::Serialize;
 
+/// A `disabled` property value; see also the `disabled` entry in [WPT upstream documentation].
+///
+/// [WPT upstream]: https://web-platform-tests.org/tools/wptrunner/docs/expectation.html#web-platform-tests-metadata
 #[derive(Clone, Debug, Eq, PartialEq, Serialize)]
 pub struct DisabledString(Cow<'static, str>);
 

moz-webgpu-cts/src/wpt/path.rs

@@ -1,3 +1,6 @@
+//! Abstractions for dealing with paths to WebGPU CTS tests. The key offerings of this module are
+//! the [`Browser`] and [`SpecPath`] APIs.
+
 use std::{
     borrow::Cow,
     fmt::{Debug, Display},