Docs

Author: 38

CHANGELOG.md

@@ -5,6 +5,11 @@
 
 - Adjust Canvas backend size with DPR (Thanks to Marius-Mueller)
 
+### Improvement
+
+- Enhanced key point algorithms: New key point hint trait are used for key point algorithms && many improvment on key point algorithms for different types
+- Renamed `MeshStyle::line\_style\_1\ and `MeshStyle::line\_style\_2` to `bold\_line\_style` and `light\_line\_style`
+
 ## Plotters 0.2.15 (2020-05-26)
 ### Fixed
 

src/coord/ckps.rs

@@ -5,31 +5,44 @@ use std::ops::Range;
 
 use super::{AsRangedCoord, DiscreteRanged, KeyPointHint, Ranged};
 
+/// The coordinate decorator that binds a key point vector.
+/// Normally, all the ranged coordinate implements its own keypoint algorithm 
+/// to determine how to render the tick mark and mesh grid. 
+/// This decorator allows customized tick mark specifiied by vector. 
+/// See [BindKeyPoints::with_key_points](trait.BindKeyPoints.html#tymethod.with_key_points) 
+/// for details.
+/// Note: For any coordinate spec wrapped by this decorator, the maxium number of labels configured by
+/// MeshStyle will be ignored and the key point function will always returns the entire vector
 pub struct WithKeyPoints<Inner: Ranged> {
     inner: Inner,
     bold_points: Vec<Inner::ValueType>,
     light_points: Vec<Inner::ValueType>,
 }
 
 impl<I: Ranged> WithKeyPoints<I> {
+    /// Specify the light key points, which is used to render the light mesh line
     pub fn with_light_points<T: IntoIterator<Item = I::ValueType>>(mut self, iter: T) -> Self {
         self.light_points.clear();
         self.light_points.extend(iter);
         self
     }
 
+    /// Get a reference to the bold points
     pub fn bold_points(&self) -> &[I::ValueType] {
         self.bold_points.as_ref()
     }
 
+    /// Get a mut reference to the bold points
     pub fn bold_points_mut(&mut self) -> &mut [I::ValueType] {
         self.bold_points.as_mut()
     }
 
+    /// Get a reference to light key points
     pub fn light_points(&self) -> &[I::ValueType] {
         self.light_points.as_ref()
     }
 
+    /// Get a mut reference to the light key points
     pub fn light_points_mut(&mut self) -> &mut [I::ValueType] {
         self.light_points.as_mut()
     }
@@ -82,6 +95,20 @@ pub trait BindKeyPoints
 where
     Self: AsRangedCoord,
 {
+    /// Bind a existing coordinate spec with a given key points vector. See [WithKeyPoints](struct.WithKeyPoints.html ) for more details.
+    /// Example:
+    /// ```
+    ///use plotters::prelude::*;
+    ///use plotters_bitmap::BitMapBackend;
+    ///let mut buffer = vec![0;1024*768*3];
+    /// let root = BitMapBackend::with_buffer(&mut buffer, (1024, 768)).into_drawing_area();
+    /// let mut chart = ChartBuilder::on(&root)
+    ///    .build_ranged(
+    ///        (0..100).with_key_points(vec![1,20,50,90]),   // <= This line will make the plot shows 4 tick marks at 1, 20, 50, 90
+    ///        0..10
+    /// ).unwrap();
+    /// chart.configure_mesh().draw().unwrap();
+    ///```
     fn with_key_points(self, points: Vec<Self::Value>) -> WithKeyPoints<Self::CoordDescType> {
         WithKeyPoints {
             inner: self.into(),
@@ -93,6 +120,11 @@ where
 
 impl<T: AsRangedCoord> BindKeyPoints for T {}
 
+/// The coordinate decorator that allows customized keypoint algorithms.
+/// Normally, all the coordinate spec implements its own key point algorith
+/// But this decorator allows you override the pre-defined key point algorithm.
+///
+/// To use this decorator, see [BindKeyPointMethod::with_key_point_func](trait.BindKeyPointMethod.html#tymethod.with_key_point_func)
 pub struct WithKeyPointMethod<R: Ranged> {
     inner: R,
     bold_func: Box<dyn Fn(usize) -> Vec<R::ValueType>>,
@@ -103,6 +135,20 @@ pub trait BindKeyPointMethod
 where
     Self: AsRangedCoord,
 {
+    /// Bind a existing coordinate spec with a given key points algorithm. See [WithKeyPointMethod](struct.WithKeyMethod.html ) for more details.
+    /// Example:
+    /// ```
+    ///use plotters::prelude::*;
+    ///use plotters_bitmap::BitMapBackend;
+    ///let mut buffer = vec![0;1024*768*3];
+    /// let root = BitMapBackend::with_buffer(&mut buffer, (1024, 768)).into_drawing_area();
+    /// let mut chart = ChartBuilder::on(&root)
+    ///    .build_ranged(
+    ///        (0..100).with_key_point_func(|n| (0..100 / n as i32).map(|x| x * 100 / n as i32).collect()),
+    ///        0..10
+    /// ).unwrap();
+    /// chart.configure_mesh().draw().unwrap();
+    ///```
     fn with_key_point_func<F: Fn(usize) -> Vec<Self::Value> + 'static>(
         self,
         func: F,
@@ -118,6 +164,7 @@ where
 impl<T: AsRangedCoord> BindKeyPointMethod for T {}
 
 impl<R: Ranged> WithKeyPointMethod<R> {
+    /// Define the light key point algorithm, by default this returns an empty set
     pub fn with_light_point_func<F: Fn(usize) -> Vec<R::ValueType> + 'static>(
         mut self,
         func: F,

src/coord/ranged.rs

@@ -43,6 +43,7 @@ pub enum KeyPointWeight {
 }
 
 impl KeyPointWeight {
+    /// Check if this key point weight setting allows light point
     pub fn allow_light_points(&self) -> bool {
         match self {
             Self::Bold => false,
@@ -51,9 +52,16 @@ impl KeyPointWeight {
     }
 }
 
+/// The trait for a hint provided to the key point algorithm used by the coordinate specs.
+/// The most important constraint is the `max_num_points` which means the algorithm could emit no more than specific number of key points
+/// `weight` is used to determine if this is used as a bold grid line or light grid line
+/// `bold_points` returns the max number of coresponding bold grid lines
 pub trait KeyPointHint {
+    /// Returns the max number of key points
     fn max_num_points(&self) -> usize;
+    /// Returns the weight for this hint
     fn weight(&self) -> KeyPointWeight;
+    /// Returns the point number constraint for the bold points
     fn bold_points(&self) -> usize {
         self.max_num_points()
     }
@@ -69,6 +77,7 @@ impl KeyPointHint for usize {
     }
 }
 
+///  The key point hint indicates we only need key point for the bold grid lines
 pub struct BoldPoints(pub usize);
 
 impl KeyPointHint for BoldPoints {
@@ -81,12 +90,14 @@ impl KeyPointHint for BoldPoints {
     }
 }
 
+/// The key point hint indicates that we are using the key points for the light grid lines
 pub struct LightPoints {
     bold_points_num: usize,
     light_limit: usize,
 }
 
 impl LightPoints {
+    /// Create a new light key point hind
     pub fn new(bold_count: usize, requested: usize) -> Self {
         Self {
             bold_points_num: bold_count,