Merge pull request #12 from antithesishq/fix-rustsdk-doc-comments

Updated doc comments (v0.1.5)

lib/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "antithesis_sdk"
-version = "0.1.4"
+version = "0.1.5"
 edition = "2021"
 rust-version = "1.62.1"
 license = "MIT"

lib/src/assert/macros.rs

@@ -80,7 +80,7 @@ macro_rules! assert_helper {
 }
 
 /// Assert that ``condition`` is true every time this function is called, **and** that it is
-/// called at least once. The corresponding test property will be viewable in the Antithesis SDK: Always group of your triage report.
+/// called at least once. The corresponding test property will be viewable in the ``Antithesis SDK: Always`` group of your triage report.
 ///
 /// # Example
 ///

lib/src/assert/mod.rs

@@ -16,8 +16,8 @@ pub static ANTITHESIS_CATALOG: [CatalogInfo];
 // Only need an ASSET_TRACKER if there are actually assertions 'hit'
 // (i.e. encountered and invoked at runtime).
 //
-// Typically runtime assertions use the macros always!(), sometimes!(), etc.
-// or, a client is using the 'raw' interface 'assert_raw' at runtime.
+// Typically runtime assertions use the macros ``always!``, ``sometimes!``, etc.
+// or, a client is using the 'raw' interface ``assert_raw`` at runtime.
 //
 pub(crate) static ASSERT_TRACKER: Lazy<Mutex<HashMap<String, TrackingInfo>>> =
     Lazy::new(|| Mutex::new(HashMap::new()));
@@ -206,8 +206,8 @@ impl AssertionInfo {
 /// assertions.
 ///
 /// Be certain to provide an assertion catalog entry
-/// for each assertion issued with assert_raw().  Assertion catalog
-/// entries are also created useing assert_raw(), by setting the value
+/// for each assertion issued with ``assert_raw()``.  Assertion catalog
+/// entries are also created using ``assert_raw()``, by setting the value
 /// of the ``hit`` parameter to false.
 ///
 /// Please refer to the general Antithesis documentation regarding the

lib/src/lib.rs

@@ -1,15 +1,7 @@
 /// The assert module enables defining [test properties](https://antithesis.com/docs/using_antithesis/properties.html)
 /// about your program or [workload](https://antithesis.com/docs/getting_started/workload.html).
 ///
-/// Whenever the environment variable ``ANTITHESIS_SDK_LOCAL_OUTPUT`` is
-/// set, these macros and functions will log to the file pointed
-/// to by that variable using a structured JSON format defined in
-/// the [Antithesis SDK docs](https://antithesis.com/docs/using_antithesis/sdk/fallback/assert.html#syntax).
-/// This allows you to make use of the Antithesis assertions module
-/// in your regular testing, or even in production. In particular,
-/// very few assertions frameworks offer a convenient way to define
-/// [Sometimes assertions](https://antithesis.com/docs/best_practices/sometimes_assertions.html), but they can be quite useful even outside
-/// Antithesis.
+/// The constant [const@LOCAL_OUTPUT] is associated with local logging, which is one of the [local execution](https://antithesis.com/docs/using_antithesis/sdk/rust/overview.html#sdk-runtime-behavior) modes.
 ///
 /// Each macro/function in this module takes a parameter called ``message``, which is
 /// a string literal identifier used to aggregate assertions.
@@ -28,6 +20,8 @@ pub use once_cell;
 
 /// The lifecycle module contains functions which inform the Antithesis
 /// environment that particular test phases or milestones have been reached.
+/// 
+/// The constant [const@LOCAL_OUTPUT] is associated with local logging, which is one of the [local execution](https://antithesis.com/docs/using_antithesis/sdk/rust/overview.html#sdk-runtime-behavior) modes.
 pub mod lifecycle;
 
 /// The random module provides functions that request both structured and unstructured randomness from the Antithesis environment.
@@ -46,18 +40,13 @@ mod internal;
 /// Convenience to import all macros and functions
 pub mod prelude;
 
-/// Global initialization logic.  Performs registration of the
-/// Antithesis assertion catalog.  This should be invoked as early as
-/// possible during program execution (invoke first thing in main).
-///
-/// If invoked more than once, only the first call will result
-/// in the assertion catalog being registered.  If not invoked at all,
-/// the assertion catalog will be registered upon the first
-/// assertion that is encountered at runtime.
+/// Global initialization logic. Performs registration of the
+/// Antithesis assertion catalog. This should be invoked as early as
+/// possible during program execution. It is recommended to call it immediately in ``main``.
 ///
-/// Warning - if assertions are included in a program, and not
-/// encountered at runtime, and antithesis_init() has not been
-/// called, then the assertions will not be reported.
+/// If called more than once, only the first call will result
+/// in the assertion catalog being registered.  If never called,
+/// the assertion catalog will be registered when it encounters the first assertion at runtime.
 ///
 /// Example:
 ///
@@ -84,8 +73,17 @@ pub fn antithesis_init() {
 
 use once_cell::sync::Lazy;
 
-/// The name of the environment variable containing a path to a file 
-/// that can be created and written to when not running in the Antithesis
-/// Testing environment.  If this environment variable is not present at
+/// A constant provided by the SDK to report the location of logged output when run locally.
+/// This constant is the name of an environment variable ``ANTITHESIS_SDK_LOCAL_OUTPUT``.
+/// ``ANTITHESIS_SDK_LOCAL_OUTPUT`` is a path to a file 
+/// that can be created and written to when running locally.  If this environment variable is not present at
 /// runtime, then no assertion and lifecycle output will be attempted.
+/// 
+/// This allows you to make use of the Antithesis assertions module
+/// in your regular testing, or even in production. In particular,
+/// very few assertions frameworks offer a convenient way to define
+/// [Sometimes assertions](https://antithesis.com/docs/best_practices/sometimes_assertions.html), but they can be quite useful even outside
+/// Antithesis.
+/// 
+/// See also the documentation for [local execution](https://antithesis.com/docs/using_antithesis/sdk/rust/overview.html#sdk-runtime-behavior).
 pub use crate::internal::LOCAL_OUTPUT;

lib/src/lifecycle.rs

@@ -45,7 +45,7 @@ pub fn setup_complete(details: &Value) {
 
 /// Indicates to Antithesis that a certain event has been reached. It sends a structured log message to Antithesis that you may later use to aid debugging.
 ///
-/// In addition to ``details``, you also provide ``name``, which is the name of the event that you are logging. This name will appear in the ``logs`` section of a [triage report](https://antithesis.com/docs/reports/triage.html).
+/// In addition to ``details``, you also provide ``name``, which is the name of the event that you are logging.
 ///
 /// # Example
 ///

lib/src/random.rs

@@ -1,6 +1,6 @@
 use crate::internal;
 
-/// Returns a uint64 value chosen by Antithesis. You should not
+/// Returns a u64 value chosen by Antithesis. You should not
 /// store this value or use it to seed a PRNG, but should use it
 /// immediately.
 ///