docs: Relate args option to Bencher

This should prevent folks from using `args` for a single value.

CHANGELOG.md

@@ -8,6 +8,10 @@ Versioning](http://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Changes
+
+- Improve [`args`] documentation by relating it to using [`Bencher`].
+
 ## [0.1.13] - 2024-02-09
 
 ### Fixed
@@ -274,6 +278,7 @@ Initial release. See [blog post](https://nikolaivazquez.com/blog/divan/).
 
 [`AllocProfiler`]: https://docs.rs/divan/0.1/divan/struct.AllocProfiler.html
 [`args`]: https://docs.rs/divan/latest/divan/attr.bench.html#args
+[`Bencher`]: https://docs.rs/divan/0.1/divan/struct.Bencher.html
 [`black_box`]: https://docs.rs/divan/latest/divan/fn.black_box.html
 [`consts`]: https://docs.rs/divan/latest/divan/attr.bench.html#consts
 

src/lib.rs

@@ -320,7 +320,15 @@ pub fn black_box_drop<T>(dummy: T) {
 /// ## `args`
 /// [`args`]: #args
 ///
-/// Divan supports providing runtime arguments to benchmarked functions.
+/// Function arguments can be provided to benchmark the function over multiple
+/// cases. This is used for comparing across parameters like collection lengths
+/// and [`enum`](https://doc.rust-lang.org/std/keyword.enum.html) variants. If
+/// you are not comparing cases and just need to pass a value into the
+/// benchmark, instead consider passing local values into the [`Bencher::bench`]
+/// closure or use [`Bencher::with_inputs`] for many distinct values.
+///
+/// The following example benchmarks converting a [`Range`](std::ops::Range) to
+/// [`Vec`] over different lengths:
 ///
 /// ```
 /// #[divan::bench(args = [1000, LEN, len()])]
@@ -402,18 +410,23 @@ pub fn black_box_drop<T>(dummy: T) {
 /// }
 /// ```
 ///
-/// Arguments can also be used with [`Bencher`]. This allows for providing
-/// throughput information via [`Counter`s](crate::counter::Counter):
+/// Arguments can also be used with [`Bencher`]. This allows for generating
+/// inputs based on [`args`] values or providing throughput information via
+/// [`Counter`s](crate::counter::Counter):
 ///
 /// ```
+/// # fn new_value<T>(v: T) -> T { v }
+/// # fn do_work<T>(_: T) {}
 /// use divan::Bencher;
 ///
 /// #[divan::bench(args = [1, 2, 3])]
 /// fn bench(bencher: Bencher, len: usize) {
+///     let value = new_value(len);
+///
 ///     bencher
 ///         .counter(len)
 ///         .bench(|| {
-///             // ...
+///             do_work(value);
 ///         });
 /// }
 /// ```