enabled rehauled and now actually works.

Plot API changes to make it easier to use without warnings & to follow
the same pattern as other macros we have.

CHANGELOG.md

@@ -5,7 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [Unreleased] - 2024-xx-xx
+
+### Added
+### Fixed
+### Changed
+### Removed
+
+## [0.0.4] - 2024-01-17
+
+### Changed
+
+- `make_plot!` now accepts the plot variable name to define.
+- `plot!` now accepts the plot variable name to emit value to.
+
+### Fixed
+
+- macroses were not properly handling `enabled` at all.
+- docs typos and absence in some places due to feature gating.
+- using code now nicely compiles without warnings for both `enabled`
+  and not cases.
 
 ## [0.0.3] - 2024-01-17
 
@@ -31,3 +50,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [0.0.1]: https://github.com/den-mentiei/tracy-gizmos/releases/tag/v0.0.1
 [0.0.2]: https://github.com/den-mentiei/tracy-gizmos/releases/tag/v0.0.1..v0.0.2
 [0.0.3]: https://github.com/den-mentiei/tracy-gizmos/releases/tag/v0.0.2..v0.0.3
+[0.0.4]: https://github.com/den-mentiei/tracy-gizmos/releases/tag/v0.0.3..v0.0.4

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name        = "tracy-gizmos"
-version     = "0.0.3"
+version     = "0.0.4"
 authors     = ["Denys Mentiei <[email protected]>"]
 description = "Bindings for the client library of the Tracy profiler"
 repository  = "https://github.com/den-mentiei/tracy-gizmos"

examples/plots.rs

@@ -9,7 +9,6 @@ use tracy_gizmos::{
 	PlotConfig,
 	PlotFormat,
 	PlotStyle,
-	PlotEmit,
 	make_plot,
 	plot,
 	zone,
@@ -32,14 +31,15 @@ fn main() {
 		.as_secs();
 
 	zone!("Plotting");
-	let percents = make_plot!("Load percentage", PlotConfig {
+
+	make_plot!(percents, "Load percentage", PlotConfig {
 		format: PlotFormat::Percentage,
 		style:  PlotStyle::Smooth,
 		color:  Color::PAPAYA_WHIP,
 		filled: true,
 	});
 
-	let highmark = make_plot!("High memory mark", PlotConfig {
+	make_plot!(highmark, "High memory mark", PlotConfig {
 		format: PlotFormat::Memory,
 		style:  PlotStyle::Staircase,
 		color:  Color::ROSY_BROWN,
@@ -51,8 +51,8 @@ fn main() {
 
 		plot!("i", i as i64);
 		plot!("random", r % 1000);
-		percents.emit(r % 100);
-		highmark.emit(r);
+		plot!(percents, r % 100);
+		plot!(highmark, r);
 
 		sleep(Duration::from_millis(10));
 	}

src/lib.rs

@@ -280,6 +280,8 @@ macro_rules! message {
 /// an unique name, use either a continuous or discontinuous frame
 /// only!
 ///
+/// Under the hood it declares a local [`Frame`].
+///
 /// # Examples
 ///
 /// Here comes all possible and interesting cases of frame marking.
@@ -339,31 +341,42 @@ macro_rules! message {
 /// }
 /// ```
 #[macro_export]
+#[cfg(any(doc, feature = "enabled"))]
 macro_rules! frame {
 	() => {
-		#[cfg(feature = "enabled")]
 		// SAFETY: Null pointer means main frame.
 		unsafe {
 			$crate::details::mark_frame_end(std::ptr::null());
 		}
 	};
 
 	($name:literal) => {
-		#[cfg(feature = "enabled")]
 		// SAFETY: We null-terminate the string.
 		unsafe {
 			$crate::details::mark_frame_end(concat!($name, '\0').as_ptr());
 		}
 	};
 
 	($var:ident, $name:literal) => {
-		#[cfg(feature = "enabled")]
+		#[allow(unused_variables)]
 		// SAFETY: We null-terminate the string.
 		let $var = unsafe {
 			$crate::details::discontinuous_frame(concat!($name, '\0').as_ptr().cast())
 		};
-		#[cfg(not(feature = "enabled"))]
-		let $var = ();
+	};
+}
+
+#[macro_export]
+#[cfg(all(not(doc), not(feature = "enabled")))]
+macro_rules! frame {
+	($($name:literal)? $($var:ident, $n:literal)?) => {
+		// $var could be used to denote a lexically scoped frame or
+		// even be manually `drop`-ed. Hence, we need to define it to
+		// keep the macro-using code compilable.
+		$(
+			#[allow(unused_variables)]
+			let $var = $crate::Frame();
+		)?
 	};
 }
 
@@ -464,6 +477,8 @@ impl Drop for TracyClient {
 /// profiled function scope, but it is also possible to measure time
 /// spent in nested loops or if branches.
 ///
+/// Under the hood it declares a local [`Zone`].
+///
 /// A custom name is required for the zone, which allows to identify
 /// it later in the Trace visualization.
 ///
@@ -547,6 +562,7 @@ impl Drop for TracyClient {
 /// parsing.text(file_path);
 /// ```
 #[macro_export]
+#[cfg(any(doc, feature = "enabled"))]
 macro_rules! zone {
 	(            $name:literal)                               => { $crate::zone!(_z,   $name, $crate::Color::UNSPECIFIED, enabled:true) };
 	($var:ident, $name:literal)                               => { $crate::zone!($var, $name, $crate::Color::UNSPECIFIED, enabled:true) };
@@ -556,47 +572,60 @@ macro_rules! zone {
 	($var:ident, $name:literal,              enabled:$e:expr) => { $crate::zone!($var, $name, $crate::Color::UNSPECIFIED, enabled:$e)   };
 	(            $name:literal, $color:expr, enabled:$e:expr) => { $crate::zone!(_z,   $name, $color,                     enabled:$e)   };
 	($var:ident, $name:literal, $color:expr, enabled:$e:expr) => {
-		#[cfg(feature = "enabled")]
+		#[allow(unused_variables)]
 		// SAFETY: This macro ensures that location & context data are correct.
 		let $var = unsafe {
 			$crate::details::zone($crate::zone!(@loc $name, $color), if $e {1} else {0})
 		};
+	};
 
-		#[cfg(not(feature = "enabled"))]
-		let $var = {
-			// Silences unused import warning.
-			_ = $color;
-			$crate::Zone::new()
+	(@loc $name:literal, $color: expr) => {{
+		// This is an implementation detail and can be changed at any moment.
+
+		#[cfg(feature = "unstable-function-names")]
+		struct X;
+		#[cfg(feature = "unstable-function-names")]
+		const FUNCTION: &'static [u8] = {
+			&$crate::details::get_fn_name_from_nested_type::<X>()
+		};
+
+		#[cfg(not(feature = "unstable-function-names"))]
+		const FUNCTION: &'static [u8] = b"<unavailable>\0";
+
+		// SAFETY: All passed data is created here and is correct.
+		static LOC: $crate::ZoneLocation = unsafe {
+			$crate::details::zone_location(
+				concat!($name, '\0'),
+				FUNCTION,
+				concat!(file!(), '\0'),
+				line!(),
+				$crate::Color::as_u32(&$color),
+			)
 		};
+		&LOC
+	}};
+}
+
+#[macro_export]
+#[cfg(all(not(doc), not(feature = "enabled")))]
+macro_rules! zone {
+	($($var:ident,)? $name:literal, enabled:$e:expr) => {
+		// Silences unused enabled expression warning.
+		_ = $e;
+		$crate::zone!($($var,)? $name, (), enabled:$e);
 	};
 
-	(@loc $name:literal, $color: expr) => {
-		#[cfg(feature = "enabled")]
-		{
-			// This is an implementation detail and can be changed at any moment.
-
-			#[cfg(feature = "unstable-function-names")]
-			struct X;
-			#[cfg(feature = "unstable-function-names")]
-			const FUNCTION: &'static [u8] = {
-				&$crate::details::get_fn_name_from_nested_type::<X>()
-			};
-
-			#[cfg(not(feature = "unstable-function-names"))]
-			const FUNCTION: &'static [u8] = b"<unavailable>\0";
-
-			// SAFETY: All passed data is created here and is correct.
-			static LOC: $crate::ZoneLocation = unsafe {
-				$crate::details::zone_location(
-					concat!($name, '\0'),
-					FUNCTION,
-					concat!(file!(), '\0'),
-					line!(),
-					$crate::Color::as_u32(&$color),
-				)
-			};
-			&LOC
-		}
+	($($var:ident,)? $name:literal $(,$color:expr)? $(,enabled:$e:expr)?) => {
+		// $var could be used to add dynamic zone data, so we need to
+		// define it to keep the macro-using code compilable.
+		$(
+			#[allow(unused_variables)]
+			let $var = $crate::Zone::new();
+		)?
+		// Silences unused `Color` import warning.
+		$(
+			_ = $color;
+		)?
 	};
 }
 
@@ -612,10 +641,11 @@ pub struct Zone {
 	_unsend: PhantomData<*mut ()>,
 }
 
-#[cfg(feature = "enabled")]
+#[cfg(any(doc, feature = "enabled"))]
 impl Drop for Zone {
 	#[inline(always)]
 	fn drop(&mut self) {
+		#[cfg(feature = "enabled")]
 		// SAFETY: The only way to have Zone is to construct it via
 		// zone! macro, which ensures that ctx value is correct.
 		unsafe {
@@ -707,10 +737,11 @@ unsafe impl Sync for ZoneLocation {}
 /// frame will be marked as finished when [`Frame`] is dropped.
 pub struct Frame(#[cfg(feature = "enabled")] *const i8);
 
-#[cfg(feature = "enabled")]
+#[cfg(any(doc, feature = "enabled"))]
 impl Drop for Frame {
 	#[inline(always)]
 	fn drop(&mut self) {
+		#[cfg(feature = "enabled")]
 		// SAFETY: The only way to have Frame is to construct it via
 		// frame! macro, which ensures that contained pointer is
 		// correct.

src/plot.rs

@@ -15,23 +15,20 @@ use crate::Color;
 /// ```
 #[macro_export]
 macro_rules! plot {
-	($name:literal, $value:expr) => {
-		#[cfg(feature = "enabled")]
-		{
-			use $crate::PlotEmit;
-			$crate::Plot::new(
-				// SAFETY: We null-terminate the string.
-				unsafe {
-					std::ffi::CStr::from_bytes_with_nul_unchecked(concat!($name, '\0').as_bytes())
-				},
-			).emit($value);
-		}
-		#[cfg(not(feature = "enabled"))]
-		{
-			// Silences unused variable warning.
-			_ = $value;
-		}
-	};
+	($name:literal, $value:expr) => {{
+		use $crate::PlotEmit;
+		$crate::Plot::new(
+			// SAFETY: We null-terminate the string.
+			unsafe {
+				std::ffi::CStr::from_bytes_with_nul_unchecked(concat!($name, '\0').as_bytes())
+			},
+		).emit($value);
+	}};
+
+	($plot:ident, $value:expr) => {{
+		use $crate::PlotEmit;
+		$plot.emit($value);
+	}};
 }
 
 /// Creates and configures the plot.
@@ -44,19 +41,34 @@ macro_rules! plot {
 /// ```no_run
 /// # use tracy_gizmos::*;
 /// let plot_config = PlotConfig { filled: true, ..Default::default() };
-/// let draw_calls  = make_plot!("Draw calls", plot_config);
-/// draw_calls.emit(10);
+/// make_plot!(draws, "Draw calls", plot_config);
+/// plot!(draws, 10);
 /// ```
 #[macro_export]
+#[cfg(any(doc, feature = "enabled"))]
 macro_rules! make_plot {
-	($name:literal, $config:expr) => {
-		$crate::Plot::with_config(
+	($var:ident, $name:literal, $config:expr) => {
+		#[allow(unused_variables)]
+		let $var = $crate::Plot::with_config(
 			// SAFETY: We null-terminate the string.
 			unsafe {
 				std::ffi::CStr::from_bytes_with_nul_unchecked(concat!($name, '\0').as_bytes())
 			},
 			$config
-		)
+		);
+	};
+}
+
+#[macro_export]
+#[cfg(all(not(doc), not(feature = "enabled")))]
+macro_rules! make_plot {
+	($var:ident, $name:literal, $config:expr) => {
+		// $var could be used with further `plot!` emissions,
+		// define it to keep the macro-using code compilable.
+		#[allow(unused_variables)]
+		let $var = $crate::Plot();
+		// Silences unused `Plot*` imports warning.
+		_ = $config;
 	};
 }