Update documentation

README.md

@@ -1 +1,9 @@
 # nvtx-rs
+
+nvtx-rs provides Rust bindings for NVIDIA's nvtx library.
+
+See the generated documentation for more details and the examples for sample usage.
+
+## Compatibility
+
+The `nvtx-rs` crate requires rustc 1.70 or greater

examples/domain.rs

@@ -26,7 +26,7 @@ fn main() {
     thread::sleep(time::Duration::from_millis(10));
     let yy = xx.success();
     thread::sleep(time::Duration::from_millis(10));
-    let zz = yy.releasing();
+    let zz = yy.release();
     drop(zz);
 
     thread::sleep(time::Duration::from_millis(10));

examples/range.rs

@@ -3,16 +3,11 @@ use std::{thread, time};
 fn main() {
     // we must hold ranges with a proper name
     // _ will not work since drop() is called immediately
-    let _x = nvtx::Range::new(
-        nvtx::EventAttributesBuilder::default()
-            .color(nvtx::color::salmon)
-            .message("Start 🦀")
-            .build(),
-    );
+    let _x = nvtx::LocalRange::new("Start 🦀");
     thread::sleep(time::Duration::from_millis(5));
     for i in 1..=10 {
         {
-            let _rng = nvtx::Range::new(
+            let _rng = nvtx::LocalRange::new(
                 nvtx::EventAttributesBuilder::default()
                     .color(nvtx::color::cornflowerblue)
                     .message(format!("Iteration Number {}", i))
@@ -21,7 +16,7 @@ fn main() {
             );
             for j in 1..=i {
                 {
-                    let _r = nvtx::Range::new(
+                    let _r = nvtx::LocalRange::new(
                         nvtx::EventAttributesBuilder::default()
                             .color(nvtx::color::beige)
                             .payload(j)

src/category.rs

@@ -1,15 +1,16 @@
-use std::sync::atomic::{AtomicU32, Ordering};
-
 use crate::Str;
+use std::sync::atomic::{AtomicU32, Ordering};
 
-/// Represents a category for use with event and range grouping. See [`crate::register_category`], [`crate::register_categories`]
+/// Represents a category for use with event and range grouping. See also: [`crate::register_category`], [`crate::register_categories`]
 #[derive(Debug, Clone, Copy)]
 pub struct Category {
     pub(super) id: u32,
 }
 
 impl Category {
     /// Create a new category not affiliated with any domain
+    ///
+    /// See [`Str`] for valid conversions
     pub fn new(name: impl Into<Str>) -> Category {
         static COUNT: AtomicU32 = AtomicU32::new(0);
         let id: u32 = 1 + COUNT.fetch_add(1, Ordering::SeqCst);

src/color.rs

@@ -1,8 +1,25 @@
 use crate::TypeValueEncodable;
+
 #[cfg(feature = "color-name")]
 pub use color_name::colors::*;
 
 /// Represents a color in use for controlling appearance within NSight Systems
+///
+/// ```
+/// // creation of a color from specific channel values:
+/// let translucent_orange = nvtx::Color::new(255, 192, 0, 128);
+///
+/// // creation of a color from pre-specified names:
+/// #[cfg(feature = "color-name")]
+/// let salmon : nvtx::Color = nvtx::color::salmon.into();
+///
+/// // modification of a color after creation:
+///
+/// let opaque_orange = translucent_orange.with_alpha(255);
+///
+/// #[cfg(feature = "color-name")]
+/// let translucent_salmon = salmon.with_alpha(128);
+///
 #[derive(Debug, Clone, Copy)]
 pub struct Color {
     /// alpha channel
@@ -28,26 +45,50 @@ impl From<[u8; 3]> for Color {
 
 impl Color {
     /// Create a new color from specified channels
-    pub fn new(a: u8, r: u8, g: u8, b: u8) -> Self {
+    ///
+    /// ```
+    /// let nice_blue = nvtx::Color::new(0, 192, 255, 255);
+    /// ```
+    pub fn new(r: u8, g: u8, b: u8, a: u8) -> Self {
         Self { a, r, g, b }
     }
 
     /// Change the alpha channel for the color and yield a new color
+    ///
+    /// ```
+    /// let nice_blue = nvtx::Color::new(0, 192, 255, 255);
+    /// let translucent_blue = nice_blue.with_alpha(128);
+    /// ```
     pub fn with_alpha(&self, a: u8) -> Self {
         Color { a, ..*self }
     }
 
     /// Change the red channel for the color and yield a new color
+    ///
+    /// ```
+    /// let dark_gray = nvtx::Color::new(32, 32, 32, 255);
+    /// let dark_red = dark_gray.with_red(128);
+    /// ```
     pub fn with_red(&self, r: u8) -> Self {
         Color { r, ..*self }
     }
 
     /// Change the green channel for the color and yield a new color
+    ///
+    /// ```
+    /// let dark_gray = nvtx::Color::new(32, 32, 32, 255);
+    /// let dark_green = dark_gray.with_green(128);
+    /// ```
     pub fn with_green(&self, g: u8) -> Self {
         Color { g, ..*self }
     }
 
     /// Change the blue channel for the color and yield a new color
+    ///
+    /// ```
+    /// let dark_gray = nvtx::Color::new(32, 32, 32, 255);
+    /// let dark_blue = dark_gray.with_blue(128);
+    /// ```
     pub fn with_blue(&self, b: u8) -> Self {
         Color { b, ..*self }
     }

src/domain.rs

@@ -1,15 +1,3 @@
-pub use self::{
-    category::Category,
-    event_argument::EventArgument,
-    event_attributes::{EventAttributes, EventAttributesBuilder},
-    identifier::Identifier,
-    local_range::LocalRange,
-    message::Message,
-    range::Range,
-    registered_string::RegisteredString,
-    resource::Resource,
-};
-pub use crate::sync;
 use crate::{Str, TypeValueEncodable};
 use std::{
     marker::PhantomData,
@@ -25,6 +13,20 @@ mod message;
 mod range;
 mod registered_string;
 mod resource;
+/// user-defined synchronization objects
+pub mod sync;
+
+pub use self::{
+    category::Category,
+    event_argument::EventArgument,
+    event_attributes::{EventAttributes, EventAttributesBuilder},
+    identifier::Identifier,
+    local_range::LocalRange,
+    message::Message,
+    range::Range,
+    registered_string::RegisteredString,
+    resource::Resource,
+};
 
 /// Represents a domain for high-level grouping
 #[derive(Debug)]
@@ -35,6 +37,12 @@ pub struct Domain {
 
 impl Domain {
     /// Register a NVTX domain
+    ///
+    /// See [`Str`] for valid conversions
+    ///
+    /// ```
+    /// let domain = nvtx::Domain::new("Domain");
+    /// ```
     pub fn new(name: impl Into<Str>) -> Self {
         Domain {
             handle: match name.into() {
@@ -46,6 +54,12 @@ impl Domain {
     }
 
     /// Gets a new builder instance for event attribute construction in the current domain
+    ///
+    /// ```
+    /// let domain = nvtx::Domain::new("Domain");
+    /// // ...
+    /// let builder = domain.event_attributes_builder();
+    /// ```
     pub fn event_attributes_builder(&self) -> EventAttributesBuilder<'_> {
         EventAttributesBuilder {
             domain: self,
@@ -57,6 +71,16 @@ impl Domain {
     }
 
     /// Registers an immutable string within the current domain
+    ///
+    /// Returns a handle to the immutable string registered to nvtx.
+    ///
+    /// See [`Str`] for valid conversions
+    ///
+    /// ```
+    /// let domain = nvtx::Domain::new("Domain");
+    /// // ...
+    /// let my_str = domain.register_string("My immutable string");
+    /// ```
     pub fn register_string(&self, string: impl Into<Str>) -> RegisteredString<'_> {
         let handle = match string.into() {
             Str::Ascii(s) => unsafe {
@@ -73,6 +97,16 @@ impl Domain {
     }
 
     /// Register many immutable strings within the current domain
+    ///
+    /// Returns an array of handles to the immutable strings registered to nvtx.
+    ///
+    /// See [`Str`] for valid conversions
+    ///
+    /// ```
+    /// let domain = nvtx::Domain::new("Domain");
+    /// // ...
+    /// let [a, b, c] = domain.register_strings(["A", "B", "C"]);
+    /// ```
     pub fn register_strings<const N: usize>(
         &self,
         strings: [impl Into<Str>; N],
@@ -81,6 +115,16 @@ impl Domain {
     }
 
     /// Register a new category within the domain. Categories are used to group sets of events.
+    ///
+    /// Returns a handle to the category registered to nvtx.
+    ///
+    /// See [`Str`] for valid conversions
+    ///
+    /// ```
+    /// let domain = nvtx::Domain::new("Domain");
+    /// // ...
+    /// let cat = domain.register_category("Category");
+    /// ```
     pub fn register_category(&self, name: impl Into<Str>) -> Category<'_> {
         let id = 1 + self.registered_categories.fetch_add(1, Ordering::SeqCst);
         match name.into() {
@@ -95,33 +139,88 @@ impl Domain {
     }
 
     /// Register new categories within the domain. Categories are used to group sets of events.
+    ///
+    /// Returns an array of handles to the categories registered to nvtx.
+    ///
+    /// See [`Str`] for valid conversions
+    ///
+    /// ```
+    /// let domain = nvtx::Domain::new("Domain");
+    /// // ...
+    /// let [cat_a, cat_b] = domain.register_categories(["CatA", "CatB"]);
+    /// ```
     pub fn register_categories<const N: usize>(
         &self,
         names: [impl Into<Str>; N],
     ) -> [Category<'_>; N] {
         names.map(|name| self.register_category(name))
     }
 
-    /// Marks an instantaneous event in the application. A marker can contain a text message or specify additional information using the event attributes structure. These attributes include a text message, color, category, and a payload. Each of the attributes is optional.
+    /// Marks an instantaneous event in the application belonging to a domain.
+    ///
+    /// A marker can contain a text message or specify additional information using the event attributes structure. These attributes include a text message, color, category, and a payload. Each of the attributes is optional.
+    ///
+    /// ```
+    /// let domain = nvtx::Domain::new("Domain");
+    /// // ...
+    /// domain.mark("Sample mark");
+    ///
+    /// domain.mark(c"Another example");
+    ///
+    /// domain.mark(domain.event_attributes_builder().message("Interesting example").color([255, 0, 0]).build());
+    ///
+    /// let reg_str = domain.register_string("Registered String");
+    /// domain.mark(&reg_str);
+    /// ```
     pub fn mark<'a>(&'a self, arg: impl Into<EventArgument<'a>>) {
-        let attribute = match arg.into() {
-            EventArgument::EventAttribute(attr) => attr,
-            EventArgument::Ascii(s) => self.event_attributes_builder().message(s).build(),
-            EventArgument::Unicode(s) => self
-                .event_attributes_builder()
-                .message(Message::Unicode(s))
-                .build(),
+        let attribute: EventAttributes<'a> = match arg.into() {
+            EventArgument::Attributes(attr) => attr,
+            EventArgument::Message(m) => m.into(),
         };
         let encoded = attribute.encode();
         unsafe { nvtx_sys::ffi::nvtxDomainMarkEx(self.handle, &encoded) }
     }
 
     /// Create an RAII-friendly, domain-owned range type which (1) cannot be moved across thread boundaries and (2) automatically ended when dropped. Panics on drop() if the opening level doesn't match the closing level (since it must model a perfect stack).
+    ///
+    /// ```
+    /// let domain = nvtx::Domain::new("Domain");
+    ///
+    /// // creation from Rust string
+    /// let range = domain.local_range("simple name");
+    ///
+    /// // creation from C string (since 1.77)
+    /// let range = domain.local_range(c"simple name");
+    ///
+    /// // creation from EventAttributes
+    /// let attr = domain.event_attributes_builder().payload(1).message("complex range").build();
+    /// let range = domain.local_range(attr);
+    ///
+    /// // explicitly end a range
+    /// drop(range)
+    /// ```
     pub fn local_range<'a>(&'a self, arg: impl Into<EventArgument<'a>>) -> LocalRange<'a> {
         LocalRange::new(arg, self)
     }
 
     /// Create an RAII-friendly, domain-owned range type which (1) can be moved across thread boundaries and (2) automatically ended when dropped
+    ///
+    /// ```
+    /// let domain = nvtx::Domain::new("Domain");
+    ///
+    /// // creation from a unicode string
+    /// let range = domain.range("simple name");
+    ///
+    /// // creation from a c string (from rust 1.77+)
+    /// let range = domain.range(c"simple name");
+    ///
+    /// // creation from EventAttributes
+    /// let attr = domain.event_attributes_builder().payload(1).message("complex range").build();
+    /// let range = domain.range(attr);
+    ///
+    /// // explicitly end a range
+    /// drop(range)
+    /// ```
     pub fn range<'a>(&'a self, arg: impl Into<EventArgument<'a>>) -> Range<'a> {
         Range::new(arg, self)
     }