fix/first release cleanup

.github/workflows/check.yaml

@@ -63,3 +63,15 @@ jobs:
         uses: taiki-e/install-action@cargo-hack
       - name: cargo hack
         run: cargo hack --feature-powerset --no-dev-deps check
+
+  doc:
+    runs-on: ubuntu-latest
+    name: nightly / doc
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install nightly
+        uses: dtolnay/rust-toolchain@nightly
+      - name: Install cargo-docs-rs
+        uses: dtolnay/install@cargo-docs-rs
+      - name: cargo docs-rs
+        run: cargo docs-rs

examples/error_with_dut.rs

@@ -26,8 +26,8 @@ async fn main() -> Result<()> {
         .build()
         .scope(dut, |r| {
             async move {
-                r.add_error_with_details(
-                    &tv::Error::builder("power-fail")
+                r.add_error_detail(
+                    tv::Error::builder("power-fail")
                         .add_software_info(&sw_info)
                         .build(),
                 )

examples/measurement_series.rs

@@ -14,8 +14,8 @@ use tv::{TestResult, TestStatus};
 
 async fn step0_measurements(step: &tv::StartedTestStep) -> Result<TestStatus, tv::OcptvError> {
     let fan_speed = step
-        .add_measurement_series_with_details(
-            tv::MeasurementSeriesInfo::builder("fan_speed")
+        .add_measurement_series_detail(
+            tv::MeasurementSeriesDetail::builder("fan_speed")
                 .unit("rpm")
                 .build(),
         )
@@ -32,17 +32,17 @@ async fn step0_measurements(step: &tv::StartedTestStep) -> Result<TestStatus, tv
 
 #[cfg(feature = "boxed-scopes")]
 async fn step1_measurements(step: &tv::StartedTestStep) -> Result<TestStatus, tv::OcptvError> {
-    step.add_measurement_series_with_details(
-        tv::MeasurementSeriesInfo::builder("temp0")
+    step.add_measurement_series_detail(
+        tv::MeasurementSeriesDetail::builder("temp0")
             .unit("C")
             .build(),
     )
     .scope(|s| {
         async move {
             let two_seconds_ago =
                 chrono::Local::now().with_timezone(&chrono_tz::UTC) - Duration::seconds(2);
-            s.add_measurement_with_details(
-                tv::MeasurementSeriesElemDetails::builder(42.into())
+            s.add_measurement_detail(
+                tv::MeasurementElementDetail::builder(42.into())
                     .timestamp(two_seconds_ago)
                     .build(),
             )
@@ -60,17 +60,17 @@ async fn step1_measurements(step: &tv::StartedTestStep) -> Result<TestStatus, tv
 
 async fn step2_measurements(step: &tv::StartedTestStep) -> Result<TestStatus, tv::OcptvError> {
     let freq0 = step
-        .add_measurement_series_with_details(
-            tv::MeasurementSeriesInfo::builder("freq0")
+        .add_measurement_series_detail(
+            tv::MeasurementSeriesDetail::builder("freq0")
                 .unit("hz")
                 .build(),
         )
         .start()
         .await?;
 
     let freq1 = step
-        .add_measurement_series_with_details(
-            tv::MeasurementSeriesInfo::builder("freq0")
+        .add_measurement_series_detail(
+            tv::MeasurementSeriesDetail::builder("freq0")
                 .unit("hz")
                 .build(),
         )

examples/measurement_single.rs

@@ -12,8 +12,8 @@ use tv::{TestResult, TestStatus};
 
 async fn run_measure_step(step: &tv::StartedTestStep) -> Result<TestStatus, tv::OcptvError> {
     step.add_measurement("temperature", 42.5.into()).await?;
-    step.add_measurement_with_details(
-        &tv::Measurement::builder("fan_speed", 1200.into())
+    step.add_measurement_detail(
+        tv::Measurement::builder("fan_speed", 1200.into())
             .unit("rpm")
             .build(),
     )

examples/measurement_subcomponent.rs

@@ -15,21 +15,21 @@ async fn run_measure_step(
     step: &tv::StartedTestStep,
     ram0: tv::DutHardwareInfo,
 ) -> Result<TestStatus, tv::OcptvError> {
-    step.add_measurement_with_details(
-        &tv::Measurement::builder("temp0", 100.5.into())
+    step.add_measurement_detail(
+        tv::Measurement::builder("temp0", 100.5.into())
             .unit("F")
             .hardware_info(&ram0)
-            .subcomponent(&tv::Subcomponent::builder("chip0").build())
+            .subcomponent(tv::Subcomponent::builder("chip0").build())
             .build(),
     )
     .await?;
 
-    let chip1_temp = step.add_measurement_series_with_details(
-        tv::MeasurementSeriesInfo::builder("temp1")
+    let chip1_temp = step.add_measurement_series_detail(
+        tv::MeasurementSeriesDetail::builder("temp1")
             .unit("C")
             .hardware_info(&ram0)
             .subcomponent(
-                &tv::Subcomponent::builder("chip1")
+                tv::Subcomponent::builder("chip1")
                     .location("U11")
                     .version("1")
                     .revision("1")
@@ -59,7 +59,7 @@ async fn run_measure_step(
 async fn main() -> Result<()> {
     let mut dut = tv::DutInfo::builder("dut0")
         .name("host0.example.com")
-        .add_platform_info(&tv::PlatformInfo::new("memory-optimized"))
+        .add_platform_info(tv::PlatformInfo::new("memory-optimized"))
         .build();
 
     dut.add_software_info(

examples/measurement_validators.rs

@@ -12,22 +12,22 @@ use ocptv::output as tv;
 use tv::{TestResult, TestStatus, ValidatorType};
 
 async fn run_measure_step(step: &tv::StartedTestStep) -> Result<TestStatus, tv::OcptvError> {
-    step.add_measurement_with_details(
-        &tv::Measurement::builder("temp", 40.into())
+    step.add_measurement_detail(
+        tv::Measurement::builder("temp", 40.into())
             .add_validator(
-                &tv::Validator::builder(ValidatorType::GreaterThan, 30.into())
+                tv::Validator::builder(ValidatorType::GreaterThan, 30.into())
                     .name("gt_30")
                     .build(),
             )
             .build(),
     )
     .await?;
 
-    step.add_measurement_series_with_details(
-        tv::MeasurementSeriesInfo::builder("fan_speed")
+    step.add_measurement_series_detail(
+        tv::MeasurementSeriesDetail::builder("fan_speed")
             .unit("rpm")
             .add_validator(
-                &tv::Validator::builder(ValidatorType::LessThanOrEqual, 3000.into()).build(),
+                tv::Validator::builder(ValidatorType::LessThanOrEqual, 3000.into()).build(),
             )
             .build(),
     )
@@ -41,8 +41,8 @@ async fn run_measure_step(step: &tv::StartedTestStep) -> Result<TestStatus, tv::
     })
     .await?;
 
-    step.add_measurement_with_details(
-        &tv::Measurement::builder("fan_speed", 1200.into())
+    step.add_measurement_detail(
+        tv::Measurement::builder("fan_speed", 1200.into())
             .unit("rpm")
             .build(),
     )

scripts/check.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+set -eo pipefail
+
+# (c) Meta Platforms, Inc. and affiliates.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+
+echo "Running CI checks..."
+
+cargo fmt --check
+
+# ensure the tests run ok with all features disabled
+cargo test
+
+cargo test --locked --all-features
+
+# docs-rs supersedes cargo doc
+cargo +nightly docs-rs
+
+# finish with coverage, so we get an output to check
+cargo llvm-cov --locked --all-features

src/output/config.rs

@@ -25,7 +25,6 @@ impl Config {
     /// # Examples
     /// ```rust
     /// # use ocptv::output::*;
-    ///
     /// let builder = Config::builder();
     /// ```
     pub fn builder() -> ConfigBuilder {
@@ -47,7 +46,7 @@ impl ConfigBuilder {
         }
     }
 
-    // TODO: docs for all these
+    /// TODO: docs for all these
     pub fn timezone(mut self, timezone: chrono_tz::Tz) -> Self {
         self.timestamp_provider = Box::new(ConfiguredTzProvider { tz: timezone });
         self
@@ -92,6 +91,7 @@ impl ConfigBuilder {
     }
 }
 
+/// TODO: docs
 pub trait TimestampProvider {
     fn now(&self) -> chrono::DateTime<chrono_tz::Tz>;
 }

src/output/diagnosis.rs

@@ -9,7 +9,8 @@ use crate::spec;
 use tv::dut;
 
 /// This structure represents a Diagnosis message.
-/// ref: https://github.com/opencomputeproject/ocp-diag-core/tree/main/json_spec#diagnosis
+///
+/// ref: <https://github.com/opencomputeproject/ocp-diag-core/tree/main/json_spec#diagnosis>
 ///
 /// Information about the source file and line number are not automatically added.
 /// Add them using the builder or the macros octptv_diagnosis_*
@@ -20,15 +21,13 @@ use tv::dut;
 ///
 /// ```
 /// # use ocptv::output::*;
-///
 /// let diagnosis = Diagnosis::new("verdict", DiagnosisType::Pass);
 /// ```
 ///
 /// ## Create a Diagnosis object with the `builder` method
 ///
 /// ```
 /// # use ocptv::output::*;
-///
 /// let mut dut = DutInfo::new("dut0");
 /// let hw_info = dut.add_hardware_info(HardwareInfo::builder("name").build());
 ///
@@ -73,7 +72,6 @@ impl Diagnosis {
     ///
     /// ```
     /// # use ocptv::output::*;
-    ///
     /// let mut dut = DutInfo::new("dut0");
     /// let hw_info = dut.add_hardware_info(HardwareInfo::builder("name").build());
     ///
@@ -94,7 +92,6 @@ impl Diagnosis {
     ///
     /// ```
     /// # use ocptv::output::*;
-    ///
     /// let diagnosis = Diagnosis::new("verdict", DiagnosisType::Pass);
     /// let _ = diagnosis.to_artifact();
     /// ```
@@ -122,7 +119,6 @@ impl Diagnosis {
 ///
 /// ```
 /// # use ocptv::output::*;
-///
 /// let mut dut = DutInfo::new("dut0");
 /// let hw_info = dut.add_hardware_info(HardwareInfo::builder("name").build());
 ///
@@ -146,16 +142,7 @@ pub struct DiagnosisBuilder {
 }
 
 impl DiagnosisBuilder {
-    /// Creates a new DiagnosisBuilder.
-    ///
-    /// # Examples
-    ///
-    /// ```
-    /// # use ocptv::output::*;
-    ///
-    /// let builder = DiagnosisBuilder::new("verdict", DiagnosisType::Pass);
-    /// ```
-    pub fn new(verdict: &str, diagnosis_type: spec::DiagnosisType) -> Self {
+    fn new(verdict: &str, diagnosis_type: spec::DiagnosisType) -> Self {
         DiagnosisBuilder {
             verdict: verdict.to_owned(),
             diagnosis_type,
@@ -169,59 +156,55 @@ impl DiagnosisBuilder {
     ///
     /// ```
     /// # use ocptv::output::*;
-    ///
-    /// let builder = DiagnosisBuilder::new("verdict", DiagnosisType::Pass)
+    /// let builder = Diagnosis::builder("verdict", DiagnosisType::Pass)
     ///     .message("message");
     /// ```
-    pub fn message(mut self, message: &str) -> DiagnosisBuilder {
+    pub fn message(mut self, message: &str) -> Self {
         self.message = Some(message.to_owned());
         self
     }
 
-    /// Add a [`HardwareInfo`] to a [`DiagnosisBuilder`].
+    /// Add a [`dut::HardwareInfo`] to a [`DiagnosisBuilder`].
     ///
     /// # Examples
     ///
     /// ```
     /// # use ocptv::output::*;
-    ///
     /// let mut dut = DutInfo::new("dut0");
     /// let hw_info = dut.add_hardware_info(HardwareInfo::builder("name").build());
     ///
-    /// let builder = DiagnosisBuilder::new("verdict", DiagnosisType::Pass)
+    /// let builder = Diagnosis::builder("verdict", DiagnosisType::Pass)
     ///     .hardware_info(&hw_info);
     /// ```
-    pub fn hardware_info(mut self, hardware_info: &dut::DutHardwareInfo) -> DiagnosisBuilder {
+    pub fn hardware_info(mut self, hardware_info: &dut::DutHardwareInfo) -> Self {
         self.hardware_info = Some(hardware_info.clone());
         self
     }
 
-    /// Add a [`Subcomponent`] to a [`DiagnosisBuilder`].
+    /// Add a [`dut::Subcomponent`] to a [`DiagnosisBuilder`].
     ///
     /// # Examples
     ///
     /// ```
     /// # use ocptv::output::*;
-    ///
-    /// let builder = DiagnosisBuilder::new("verdict", DiagnosisType::Pass)
+    /// let builder = Diagnosis::builder("verdict", DiagnosisType::Pass)
     ///     .subcomponent(&Subcomponent::builder("name").build());
     /// ```
-    pub fn subcomponent(mut self, subcomponent: &dut::Subcomponent) -> DiagnosisBuilder {
+    pub fn subcomponent(mut self, subcomponent: &dut::Subcomponent) -> Self {
         self.subcomponent = Some(subcomponent.clone());
         self
     }
 
-    /// Add a [`SourceLocation`] to a [`DiagnosisBuilder`].
+    /// Add a source location to a [`DiagnosisBuilder`].
     ///
     /// # Examples
     ///
     /// ```
     /// # use ocptv::output::*;
-    ///
-    /// let builder = DiagnosisBuilder::new("verdict", DiagnosisType::Pass)
+    /// let builder = Diagnosis::builder("verdict", DiagnosisType::Pass)
     ///     .source("file.rs", 1);
     /// ```
-    pub fn source(mut self, file: &str, line: i32) -> DiagnosisBuilder {
+    pub fn source(mut self, file: &str, line: i32) -> Self {
         self.source_location = Some(spec::SourceLocation {
             file: file.to_owned(),
             line,
@@ -235,8 +218,7 @@ impl DiagnosisBuilder {
     ///
     /// ```
     /// # use ocptv::output::*;
-    ///
-    /// let builder = DiagnosisBuilder::new("verdict", DiagnosisType::Pass);
+    /// let builder = Diagnosis::builder("verdict", DiagnosisType::Pass);
     /// let diagnosis = builder.build();
     /// ```
     pub fn build(self) -> Diagnosis {