From 81aa4c65d7202128d471b3a452a0236e03f3bc43 Mon Sep 17 00:00:00 2001 From: Dominik Korsa Date: Tue, 28 Nov 2023 10:36:12 +0100 Subject: [PATCH] Add more item links in docs (#607) --- src/draw_target.rs | 3 ++- src/iter.rs | 19 ++++++++++--------- src/lib.rs | 21 +++++++++++---------- src/multi.rs | 28 ++++++++++++++-------------- src/progress_bar.rs | 28 ++++++++++++++-------------- 5 files changed, 51 insertions(+), 48 deletions(-) diff --git a/src/draw_target.rs b/src/draw_target.rs index 05e658b1..5f9b66c9 100644 --- a/src/draw_target.rs +++ b/src/draw_target.rs @@ -14,7 +14,8 @@ use crate::TermLike; /// Target for draw operations /// -/// This tells a progress bar or a multi progress object where to paint to. +/// This tells a [`ProgressBar`](crate::ProgressBar) or a +/// [`MultiProgress`](crate::MultiProgress) object where to paint to. /// The draw target is a stateful wrapper over a drawing destination and /// internally optimizes how often the state is painted to the output /// device. diff --git a/src/iter.rs b/src/iter.rs index 73e83824..8861db52 100644 --- a/src/iter.rs +++ b/src/iter.rs @@ -19,9 +19,10 @@ pub trait ProgressIterator where Self: Sized + Iterator, { - /// Wrap an iterator with default styling. Uses `Iterator::size_hint` to get length. - /// Returns `Some(..)` only if `size_hint.1` is `Some`. If you want to create a progress bar - /// even if `size_hint.1` returns `None` use `progress_count` or `progress_with` instead. + /// Wrap an iterator with default styling. Uses [`Iterator::size_hint()`] to get length. + /// Returns `Some(..)` only if `size_hint.1` is [`Some`]. If you want to create a progress bar + /// even if `size_hint.1` returns [`None`] use [`progress_count()`](ProgressIterator::progress_count) + /// or [`progress_with()`](ProgressIterator::progress_with) instead. fn try_progress(self) -> Option> { self.size_hint() .1 @@ -66,7 +67,7 @@ pub struct ProgressBarIter { impl ProgressBarIter { /// Builder-like function for setting underlying progress bar's style. /// - /// See [`ProgressBar::with_style`]. + /// See [`ProgressBar::with_style()`]. pub fn with_style(mut self, style: ProgressStyle) -> Self { self.progress = self.progress.with_style(style); self @@ -74,7 +75,7 @@ impl ProgressBarIter { /// Builder-like function for setting underlying progress bar's prefix. /// - /// See [`ProgressBar::with_prefix`]. + /// See [`ProgressBar::with_prefix()`]. pub fn with_prefix(mut self, prefix: impl Into>) -> Self { self.progress = self.progress.with_prefix(prefix); self @@ -82,7 +83,7 @@ impl ProgressBarIter { /// Builder-like function for setting underlying progress bar's message. /// - /// See [`ProgressBar::with_message`]. + /// See [`ProgressBar::with_message()`]. pub fn with_message(mut self, message: impl Into>) -> Self { self.progress = self.progress.with_message(message); self @@ -90,7 +91,7 @@ impl ProgressBarIter { /// Builder-like function for setting underlying progress bar's position. /// - /// See [`ProgressBar::with_position`]. + /// See [`ProgressBar::with_position()`]. pub fn with_position(mut self, position: u64) -> Self { self.progress = self.progress.with_position(position); self @@ -98,7 +99,7 @@ impl ProgressBarIter { /// Builder-like function for setting underlying progress bar's elapsed time. /// - /// See [`ProgressBar::with_elapsed`]. + /// See [`ProgressBar::with_elapsed()`]. pub fn with_elapsed(mut self, elapsed: Duration) -> Self { self.progress = self.progress.with_elapsed(elapsed); self @@ -106,7 +107,7 @@ impl ProgressBarIter { /// Builder-like function for setting underlying progress bar's finish behavior. /// - /// See [`ProgressBar::with_finish`]. + /// See [`ProgressBar::with_finish()`]. pub fn with_finish(mut self, finish: ProgressFinish) -> Self { self.progress = self.progress.with_finish(finish); self diff --git a/src/lib.rs b/src/lib.rs index 5dc3ff84..2f7c8e9d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -28,12 +28,12 @@ //! //! # Progress Bars and Spinners //! -//! indicatif comes with a `ProgressBar` type that supports both bounded +//! indicatif comes with a [`ProgressBar`] type that supports both bounded //! progress bar uses as well as unbounded "spinner" type progress reports. -//! Progress bars are `Sync` and `Send` objects which means that they are +//! Progress bars are [`Sync`] and [`Send`] objects which means that they are //! internally locked and can be passed from thread to thread. //! -//! Additionally a `MultiProgress` utility is provided that can manage +//! Additionally a [`MultiProgress`] utility is provided that can manage //! rendering multiple progress bars at once (eg: from multiple threads). //! //! To whet your appetite, this is what this can look like: @@ -56,8 +56,8 @@ //! bar.finish(); //! ``` //! -//! Spinners can be manually advanced with `tick`, or you can set them up to spin automatically with -//! `enable_steady_tick`: +//! Spinners can be manually advanced with [`tick`](ProgressBar::tick), or you can set them up +//! to spin automatically with [`enable_steady_tick`](ProgressBar::enable_steady_tick): //! //! ```rust //! use std::time::Duration; @@ -74,9 +74,10 @@ //! * if a non terminal is detected the progress bar will be completely //! hidden. This makes piping programs to logfiles make sense out of //! the box. -//! * a progress bar only starts drawing when `set_message`, `inc`, `set_position` -//! or `tick` are called. In some situations you might have to call `tick` -//! once to draw it. +//! * a progress bar only starts drawing when [`set_message`](ProgressBar::set_message), +//! [`inc`](ProgressBar::inc), [`set_position`](ProgressBar::set_position) +//! or [`tick`](ProgressBar::tick) are called. In some situations you +//! might have to call [`tick`](ProgressBar::tick) once to draw it. //! * progress bars should be explicitly finished to reset the rendering //! for others. Either by also clearing them or by replacing them with //! a new message / retaining the current message. @@ -147,7 +148,7 @@ //! ``` //! //! For the style component see [`Style::from_dotted_str`](https://docs.rs/console/0.7.5/console/struct.Style.html#method.from_dotted_str) -//! for more information. Indicatif uses the `console` base crate for all +//! for more information. Indicatif uses the `console` base crate for all //! colorization and formatting options. //! //! Some examples for templates: @@ -206,7 +207,7 @@ //! //! The design of the progress bar can be altered with the integrated //! template functionality. The template can be set by changing a -//! `ProgressStyle` and attaching it to the progress bar. +//! [`ProgressStyle`] and attaching it to the progress bar. //! //! # Human Readable Formatting //! diff --git a/src/multi.rs b/src/multi.rs index 7d287bfa..b77cdb70 100644 --- a/src/multi.rs +++ b/src/multi.rs @@ -68,12 +68,12 @@ impl MultiProgress { /// /// The progress bar added will have the draw target changed to a /// remote draw target that is intercepted by the multi progress - /// object overriding custom `ProgressDrawTarget` settings. + /// object overriding custom [`ProgressDrawTarget`] settings. /// /// The progress bar will be positioned below all other bars currently - /// in the `MultiProgress`. + /// in the [`MultiProgress`]. /// - /// Adding a progress bar that is already a member of the `MultiProgress` + /// Adding a progress bar that is already a member of the [`MultiProgress`] /// will have no effect. pub fn add(&self, pb: ProgressBar) -> ProgressBar { self.internalize(InsertLocation::End, pb) @@ -83,12 +83,12 @@ impl MultiProgress { /// /// The progress bar inserted at position `index` will have the draw /// target changed to a remote draw target that is intercepted by the - /// multi progress object overriding custom `ProgressDrawTarget` settings. + /// multi progress object overriding custom [`ProgressDrawTarget`] settings. /// /// If `index >= MultiProgressState::objects.len()`, the progress bar /// is added to the end of the list. /// - /// Inserting a progress bar that is already a member of the `MultiProgress` + /// Inserting a progress bar that is already a member of the [`MultiProgress`] /// will have no effect. pub fn insert(&self, index: usize, pb: ProgressBar) -> ProgressBar { self.internalize(InsertLocation::Index(index), pb) @@ -99,12 +99,12 @@ impl MultiProgress { /// The progress bar inserted at position `MultiProgressState::objects.len() - index` /// will have the draw target changed to a remote draw target that is /// intercepted by the multi progress object overriding custom - /// `ProgressDrawTarget` settings. + /// [`ProgressDrawTarget`] settings. /// /// If `index >= MultiProgressState::objects.len()`, the progress bar /// is added to the start of the list. /// - /// Inserting a progress bar that is already a member of the `MultiProgress` + /// Inserting a progress bar that is already a member of the [`MultiProgress`] /// will have no effect. pub fn insert_from_back(&self, index: usize, pb: ProgressBar) -> ProgressBar { self.internalize(InsertLocation::IndexFromBack(index), pb) @@ -114,9 +114,9 @@ impl MultiProgress { /// /// The progress bar added will have the draw target changed to a /// remote draw target that is intercepted by the multi progress - /// object overriding custom `ProgressDrawTarget` settings. + /// object overriding custom [`ProgressDrawTarget`] settings. /// - /// Inserting a progress bar that is already a member of the `MultiProgress` + /// Inserting a progress bar that is already a member of the [`MultiProgress`] /// will have no effect. pub fn insert_before(&self, before: &ProgressBar, pb: ProgressBar) -> ProgressBar { self.internalize(InsertLocation::Before(before.index().unwrap()), pb) @@ -126,9 +126,9 @@ impl MultiProgress { /// /// The progress bar added will have the draw target changed to a /// remote draw target that is intercepted by the multi progress - /// object overriding custom `ProgressDrawTarget` settings. + /// object overriding custom [`ProgressDrawTarget`] settings. /// - /// Inserting a progress bar that is already a member of the `MultiProgress` + /// Inserting a progress bar that is already a member of the [`MultiProgress`] /// will have no effect. pub fn insert_after(&self, after: &ProgressBar, pb: ProgressBar) -> ProgressBar { self.internalize(InsertLocation::After(after.index().unwrap()), pb) @@ -137,7 +137,7 @@ impl MultiProgress { /// Removes a progress bar. /// /// The progress bar is removed only if it was previously inserted or added - /// by the methods `MultiProgress::insert` or `MultiProgress::add`. + /// by the methods [`MultiProgress::insert`] or [`MultiProgress::add`]. /// If the passed progress bar does not satisfy the condition above, /// the `remove` method does nothing. pub fn remove(&self, pb: &ProgressBar) { @@ -494,14 +494,14 @@ impl Debug for MultiStateMember { /// Vertical alignment of a multi progress. /// /// The alignment controls how the multi progress is aligned if some of its progress bars get removed. -/// E.g. `Top` alignment (default), when _progress bar 2_ is removed: +/// E.g. [`Top`](MultiProgressAlignment::Top) alignment (default), when _progress bar 2_ is removed: /// ```ignore /// [0/100] progress bar 1 [0/100] progress bar 1 /// [0/100] progress bar 2 => [0/100] progress bar 3 /// [0/100] progress bar 3 /// ``` /// -/// `Bottom` alignment +/// [`Bottom`](MultiProgressAlignment::Bottom) alignment /// ```ignore /// [0/100] progress bar 1 /// [0/100] progress bar 2 => [0/100] progress bar 1 diff --git a/src/progress_bar.rs b/src/progress_bar.rs index 44befefc..bd01da57 100644 --- a/src/progress_bar.rs +++ b/src/progress_bar.rs @@ -122,7 +122,7 @@ impl ProgressBar { /// [`ProgressBarIter`] completes and /// [`ProgressBar::is_finished()`] is false. /// If you don't want the progress bar to be automatically finished then - /// call `on_finish(None)`. + /// call `with_finish(Abandon)`. /// /// [`ProgressBar`]: crate::ProgressBar /// [`ProgressBarIter`]: crate::ProgressBarIter @@ -237,12 +237,12 @@ impl ProgressBar { /// /// If the progress bar is hidden (e.g. when standard output is not a terminal), `println()` /// will not do anything. If you want to write to the standard output in such cases as well, use - /// [`suspend`] instead. + /// [`ProgressBar::suspend()`] instead. /// /// If the progress bar was added to a [`MultiProgress`], the log line will be /// printed above all other progress bars. /// - /// [`suspend`]: ProgressBar::suspend + /// [`ProgressBar::suspend()`]: ProgressBar::suspend /// [`MultiProgress`]: crate::MultiProgress pub fn println>(&self, msg: I) { self.state().println(Instant::now(), msg.as_ref()); @@ -293,7 +293,7 @@ impl ProgressBar { state.update_estimate_and_draw(Instant::now()); } - /// Creates a new weak reference to this `ProgressBar` + /// Creates a new weak reference to this [`ProgressBar`] pub fn downgrade(&self) -> WeakProgressBar { WeakProgressBar { state: Arc::downgrade(&self.state), @@ -378,14 +378,14 @@ impl ProgressBar { /// ``` /// /// **Note:** Calling this method on a [`ProgressBar`] linked with a [`MultiProgress`] (after - /// running [`MultiProgress::add`]) will unlink this progress bar. If you don't want this - /// behavior, call [`MultiProgress::set_draw_target`] instead. + /// running [`MultiProgress::add()`]) will unlink this progress bar. If you don't want this + /// behavior, call [`MultiProgress::set_draw_target()`] instead. /// - /// Use [`ProgressBar::with_draw_target`] to set the draw target during creation. + /// Use [`ProgressBar::with_draw_target()`] to set the draw target during creation. /// /// [`MultiProgress`]: crate::MultiProgress - /// [`MultiProgress::add`]: crate::MultiProgress::add - /// [`MultiProgress::set_draw_target`]: crate::MultiProgress::set_draw_target + /// [`MultiProgress::add()`]: crate::MultiProgress::add + /// [`MultiProgress::set_draw_target()`]: crate::MultiProgress::set_draw_target pub fn set_draw_target(&self, target: ProgressDrawTarget) { let mut state = self.state(); state.draw_target.disconnect(Instant::now()); @@ -396,7 +396,7 @@ impl ProgressBar { /// /// Useful for external code that writes to the standard output. /// - /// If the progress bar was added to a [`MultiProgress`], it will suspend the entire `MultiProgress`]. + /// If the progress bar was added to a [`MultiProgress`], it will suspend the entire [`MultiProgress`]. /// /// **Note:** The internal lock is held while `f` is executed. Other threads trying to print /// anything on the progress bar will be blocked until `f` finishes. @@ -593,7 +593,7 @@ impl ProgressBar { } } -/// A weak reference to a `ProgressBar`. +/// A weak reference to a [`ProgressBar`]. /// /// Useful for creating custom steady tick implementations #[derive(Clone, Default)] @@ -604,15 +604,15 @@ pub struct WeakProgressBar { } impl WeakProgressBar { - /// Create a new `WeakProgressBar` that returns `None` when [`upgrade`] is called. + /// Create a new [`WeakProgressBar`] that returns `None` when [`upgrade()`] is called. /// - /// [`upgrade`]: WeakProgressBar::upgrade + /// [`upgrade()`]: WeakProgressBar::upgrade pub fn new() -> Self { Self::default() } /// Attempts to upgrade the Weak pointer to a [`ProgressBar`], delaying dropping of the inner - /// value if successful. Returns `None` if the inner value has since been dropped. + /// value if successful. Returns [`None`] if the inner value has since been dropped. /// /// [`ProgressBar`]: struct.ProgressBar.html pub fn upgrade(&self) -> Option {