Update some documentations

Author: 38

src/chart/context.rs

@@ -84,6 +84,26 @@ pub struct ChartContext<'a, DB: DrawingBackend, CT: CoordTranslate> {
 ///
 /// For each frame, instead of updating the entire backend, we are able to keep the keep the figure
 /// component like axis, labels untouched and make updates only in the plotting drawing area.
+/// This is very useful for incremental render.
+/// ```rust
+///   use plotters::prelude::*;
+///    let mut buffer = vec![0u8;1024*768*3];
+///    let area = BitMapBackend::with_buffer(&mut buffer[..], (1024, 768))
+///        .into_drawing_area()
+///        .split_evenly((1,2));
+///    let chart = ChartBuilder::on(&area[0])
+///        .caption("Incremental Example", ("sans-serif", 20))
+///        .set_all_label_area_size(30)
+///        .build_ranged(0..10, 0..10)
+///        .expect("Unable to build ChartContext");
+///    // Draw the first frame at this point
+///    area[0].present().expect("Present");
+///    let state = chart.into_chart_state();
+///    // Let's draw the second frame
+///    let chart = state.restore(&area[0]);
+///    chart.plotting_area().fill(&WHITE).unwrap(); // Clear the previously drawn graph
+///    // At this point, you are able to draw next frame
+///```
 pub struct ChartState<CT: CoordTranslate> {
     drawing_area_pos: (i32, i32),
     drawing_area_size: (u32, u32),
@@ -112,7 +132,7 @@ impl<'a, DB: DrawingBackend, CT: CoordTranslate> From<ChartContext<'a, DB, CT>>
 
 impl<'a, DB: DrawingBackend, CT: CoordTranslate> ChartContext<'a, DB, CT> {
     /// Convert a chart context into a chart state, by doing so, the chart context is consumed and
-    /// a saved chart state is created for later use.
+    /// a saved chart state is created for later use. This is typically used in incrmental rendering. See documentation of `ChartState` for more detailed example.
     pub fn into_chart_state(self) -> ChartState<CT> {
         self.into()
     }
@@ -201,7 +221,7 @@ impl<
     }
 
     /// Initialize a mesh configuration object and mesh drawing can be finalized by calling
-    /// the function `MeshStyle::draw`
+    /// the function `MeshStyle::draw`.
     pub fn configure_mesh<'b>(&'b mut self) -> MeshStyle<'a, 'b, X, Y, DB> {
         let base_tick_size = (5u32).percent().max(5).in_pixels(&self.drawing_area);
 
@@ -258,6 +278,7 @@ impl<'a, DB: DrawingBackend + 'a, CT: CoordTranslate> ChartContext<'a, DB, CT> {
 }
 
 impl<'a, DB: DrawingBackend, CT: CoordTranslate> ChartContext<'a, DB, CT> {
+    /// Cast the reference to a chart context to a reference to underlying coordinate specification.
     pub fn as_coord_spec(&self) -> &CT {
         self.drawing_area.as_coord_spec()
     }
@@ -354,7 +375,8 @@ impl<'a, DB: DrawingBackend, X: Ranged, Y: Ranged> ChartContext<'a, DB, RangedCo
         &mut self.series_anno[idx]
     }
 
-    /// Draw a data series. A data series in Plotters is abstracted as an iterator of elements
+    /// Draw a data series. A data series in Plotters is abstracted as an iterator of elements.
+    /// - **Returns**: Either drawing error or a series annotation object thus we can put annotation to current series (e.g. legend)
     pub fn draw_series<E, R, S>(
         &mut self,
         series: S,
@@ -724,7 +746,8 @@ impl<'a, DB: DrawingBackend, X: Ranged, Y: Ranged> ChartContext<'a, DB, RangedCo
         Ok(())
     }
 
-    /// Convert this chart context into a dual axis chart context
+    /// Convert this chart context into a dual axis chart context and attach a second coordinate spec
+    /// on the chart context. For more detailed information, see documentation for [struct DualCoordChartContext](struct.DualCoordChartContext.html)
     ///
     /// - `x_coord`: The coordinate spec for the X axis
     /// - `y_coord`: The coordinate spec for the Y axis

src/chart/dual_coord.rs

@@ -15,14 +15,22 @@ use crate::element::{Drawable, PointCollection};
 
 use plotters_backend::{BackendCoord, DrawingBackend};
 
-/// The chart context that has two coordinate system attached
+/// The chart context that has two coordinate system attached.
+/// This situation is quite common, for example, we with two different coodinate system.
+/// For instance this example <img src="https://plotters-rs.github.io/plotters-doc-data/twoscale.png"></img>
+/// This is done by attaching  a second coordinate system to ChartContext by method [ChartContext::set_secondary_coord](struct.ChartContext.html#method.set_secondary_coord).
+/// For instance of dual coordinate charts, see [this example](https://github.com/38/plotters/blob/master/examples/two-scales.rs#L15).
+/// Note: `DualCoordChartContext` is always deref to the chart context.
+/// - If you want to configure the secondary axis, method [DualCoordChartContext::configure_secondary_axes](struct.DualCoordChartContext.html#method.configure_secondary_axes)
+/// - If you want to draw a series using secondary coordinate system, use [DualCoordChartContext::draw_secondary_series](struct.DualCoordChartContext.html#method.draw_secondary_series). And method [ChartContext::draw_series](struct.ChartContext.html#method.draw_series) will always use primary coordinate spec.
 pub struct DualCoordChartContext<'a, DB: DrawingBackend, CT1: CoordTranslate, CT2: CoordTranslate> {
     pub(super) primary: ChartContext<'a, DB, CT1>,
     pub(super) secondary: ChartContext<'a, DB, CT2>,
 }
 
 /// The chart state for a dual coord chart, see the detailed description for `ChartState` for more
-/// information about the purpose of a chart state
+/// information about the purpose of a chart state.
+/// Similar to [ChartState](struct.ChartState.html), but used for the dual coordinate charts.
 pub struct DualCoordChartState<CT1: CoordTranslate, CT2: CoordTranslate> {
     primary: ChartState<CT1>,
     secondary: ChartState<CT2>,
@@ -31,15 +39,15 @@ pub struct DualCoordChartState<CT1: CoordTranslate, CT2: CoordTranslate> {
 impl<'a, DB: DrawingBackend, CT1: CoordTranslate, CT2: CoordTranslate>
     DualCoordChartContext<'a, DB, CT1, CT2>
 {
-    /// Convert the chart context into a chart state
+    /// Convert the chart context into a chart state, similar to [ChartContext::into_chart_state](struct.ChartContext.html#method.into_chart_state)
     pub fn into_chart_state(self) -> DualCoordChartState<CT1, CT2> {
         DualCoordChartState {
             primary: self.primary.into(),
             secondary: self.secondary.into(),
         }
     }
 
-    /// Convert the chart context into a sharable chart state
+    /// Convert the chart context into a sharable chart state.
     pub fn into_shared_chart_state(self) -> DualCoordChartState<Arc<CT1>, Arc<CT2>> {
         DualCoordChartState {
             primary: self.primary.into_shared_chart_state(),
@@ -54,7 +62,7 @@ where
     CT1: Clone,
     CT2: Clone,
 {
-    /// Copy the coordinate specs and make the chart state
+    /// Copy the coordinate specs and make a chart state
     pub fn to_chart_state(&self) -> DualCoordChartState<CT1, CT2> {
         DualCoordChartState {
             primary: self.primary.to_chart_state(),
@@ -183,7 +191,7 @@ where
 impl<'a, DB: DrawingBackend, X: Ranged, Y: Ranged, SX: Ranged, SY: Ranged>
     DualCoordChartContext<'a, DB, RangedCoord<X, Y>, RangedCoord<SX, SY>>
 {
-    /// Draw a series use the secondary coordinate system
+    /// Draw a series use the secondary coordinate system.
     /// - `series`: The series to draw
     /// - `Returns` the series annotation object or error code
     pub fn draw_secondary_series<E, R, S>(

src/chart/mesh.rs

@@ -37,15 +37,17 @@ where
     }
 
     /// The offset of x labels. This is used when we want to place the label in the middle of
-    /// the grid. This is useful if we are drawing a histogram
+    /// the grid. This is used to adjust label position for histograms, but since plotters 0.3, this
+    /// use case is deprecated, see [CentricDiscreteRanged coord decorator](../coord/trait.IntoCentric.html) for more details
     /// - `value`: The offset in pixel
     pub fn x_label_offset<S: SizeDesc>(&mut self, value: S) -> &mut Self {
         self.style.x_label_offset(value);
         self
     }
 
     /// The offset of y labels. This is used when we want to place the label in the middle of
-    /// the grid. This is useful if we are drawing a histogram
+    /// the grid. This is used to adjust label position for histograms, but since plotters 0.3, this
+    /// use case is deprecated, see [CentricDiscreteRanged coord decorator](../coord/trait.IntoCentric.html) for more details
     /// - `value`: The offset in pixel
     pub fn y_label_offset<S: SizeDesc>(&mut self, value: S) -> &mut Self {
         self.style.y_label_offset(value);
@@ -202,15 +204,17 @@ where
     }
 
     /// The offset of x labels. This is used when we want to place the label in the middle of
-    /// the grid. This is useful if we are drawing a histogram
+    /// the grid. This is used to adjust label position for histograms, but since plotters 0.3, this
+    /// use case is deprecated, see [CentricDiscreteRanged coord decorator](../coord/trait.IntoCentric.html) for more details
     /// - `value`: The offset in pixel
     pub fn x_label_offset<S: SizeDesc>(&mut self, value: S) -> &mut Self {
         self.x_label_offset = value.in_pixels(&self.parent_size);
         self
     }
 
     /// The offset of y labels. This is used when we want to place the label in the middle of
-    /// the grid. This is useful if we are drawing a histogram
+    /// the grid. This is used to adjust label position for histograms, but since plotters 0.3, this
+    /// use case is deprecated, see [CentricDiscreteRanged coord decorator](../coord/trait.IntoCentric.html) for more details
     /// - `value`: The offset in pixel
     pub fn y_label_offset<S: SizeDesc>(&mut self, value: S) -> &mut Self {
         self.y_label_offset = value.in_pixels(&self.parent_size);

src/chart/mod.rs

@@ -21,5 +21,5 @@ mod series;
 pub use builder::{ChartBuilder, LabelAreaPosition};
 pub use context::{ChartContext, ChartState, SeriesAnno};
 pub use dual_coord::{DualCoordChartContext, DualCoordChartState};
-pub use mesh::MeshStyle;
+pub use mesh::{MeshStyle, SecondaryMeshStyle};
 pub use series::{SeriesLabelPosition, SeriesLabelStyle};

src/coord/datetime.rs

@@ -4,7 +4,8 @@ use std::ops::{Add, Range, Sub};
 
 use super::{AsRangedCoord, DiscreteRanged, Ranged, ValueFormatter};
 
-/// The trait that describe some time value
+/// The trait that describe some time value. This is the uniformed abstraction that works
+/// for both Date, DateTime and Duration, etc.
 pub trait TimeValue: Eq {
     type DateType: Datelike + PartialOrd;
 
@@ -16,12 +17,12 @@ pub trait TimeValue: Eq {
     fn earliest_after_date(date: Self::DateType) -> Self;
     /// Returns the duration between two time value
     fn subtract(&self, other: &Self) -> Duration;
-    /// Get the timezone information for current value
+    /// Instantiate a date type for current time value;
     fn ymd(&self, year: i32, month: u32, date: u32) -> Self::DateType;
     /// Cast current date type into this type
     fn from_date(date: Self::DateType) -> Self;
 
-    /// Map the coord
+    /// Map the coord spec
     fn map_coord(value: &Self, begin: &Self, end: &Self, limit: (i32, i32)) -> i32 {
         let total_span = end.subtract(begin);
         let value_span = value.subtract(begin);
@@ -34,6 +35,7 @@ pub trait TimeValue: Eq {
             }
         }
 
+        // Yes, converting them to floating point may lose precision, but this is Ok.
         // If it overflows, it means we have a time span nearly 300 years, we are safe to ignore the
         // portion less than 1 day.
         let total_days = total_span.num_days() as f64;

src/coord/discrete.rs

@@ -81,7 +81,12 @@ where
     }
 }
 
-/// The axis decorator that makes key-point in the center of the value range
+/// For any discrete ranged coordiante, one possible transformation is instead of using the exact point to represent the value
+/// We are now using an interval [value, value + 1) as the representation of that value.
+/// A good example for this transformation is histogram's bucket, each bucket is actually represented by a interval instead of a single point.
+/// In addition to that, all the labels should be appreas in the middle of the representing intervals.
+///
+/// The `CentricDiscreteRange` decorator that makes key-point in the center of the value range
 /// This is useful when we draw a histogram, since we want the axis value label
 /// to be shown in the middle of the range rather than exactly the location where
 /// the value mapped to.
@@ -93,7 +98,7 @@ impl<D: DiscreteRanged + Clone> Clone for CentricDiscreteRange<D> {
     }
 }
 
-/// The trait for types that can decorated by `CentricDiscreteRange` decorator
+/// The trait for types that can decorated by `CentricDiscreteRange` decorator. See [struct CentricDiscreteRange](struct.CentricDiscreteRange.html) for details.
 pub trait IntoCentric: AsRangedCoord
 where
     Self::CoordDescType: DiscreteRanged,
@@ -106,11 +111,14 @@ where
 
 impl<R: AsRangedCoord> IntoCentric for R where R::CoordDescType: DiscreteRanged {}
 
-/// The value that used by the centric coordinate
+/// The value that used by the centric coordinate.
 #[derive(Clone, Debug)]
 pub enum CentricValues<T> {
+    /// Means we are referring the exact position of value `T`
     Exact(T),
+    /// Means we are referring the center of position `T` and the successor of `T`
     CenterOf(T),
+    /// Referring the last dummy element
     Last,
 }
 
@@ -198,6 +206,7 @@ impl<T> From<T> for CentricValues<T> {
     }
 }
 
+/// The iterator that can be used to iterate all the values defined by a discrete coordinate
 pub struct DiscreteValueIter<'a, T: DiscreteRanged>(&'a T, usize, usize);
 
 impl<'a, T: DiscreteRanged> Iterator for DiscreteValueIter<'a, T> {

src/coord/group_by.rs

@@ -53,6 +53,7 @@ impl<T: DiscreteRanged> Ranged for GroupBy<T> {
     fn range(&self) -> Range<T::ValueType> {
         self.0.range()
     }
+    // TODO: See issue #88
     fn key_points(&self, max_points: usize) -> Vec<T::ValueType> {
         let range = 0..(self.0.size() + self.1 - 1) / self.1;
         let logic_range: RangedCoordusize = range.into();

src/coord/mod.rs

@@ -49,7 +49,7 @@ pub use ranged::{
 
 pub use partial_axis::{make_partial_axis, IntoPartialAxis};
 
-pub use discrete::{CentricValues, DiscreteRanged, IntoCentric};
+pub use discrete::{CentricDiscreteRange, CentricValues, DiscreteRanged, IntoCentric};
 pub use linspace::{IntoLinspace, Linspace};
 
 pub use logarithmic::{LogCoord, LogRange, LogScalable};

src/coord/nested.rs

@@ -1,7 +1,7 @@
 use super::{AsRangedCoord, DiscreteRanged, Ranged, ValueFormatter};
 use std::ops::Range;
 
-/// Describe a value for a nested croodinate
+/// Describe a value for a nested coordinate
 #[derive(PartialEq, Eq, Clone, Debug)]
 pub enum NestedValue<C, V> {
     /// Category value

src/coord/ranged.rs

@@ -14,13 +14,17 @@ pub trait DefaultValueFormatOption {}
 pub struct DefaultFormatting;
 impl DefaultValueFormatOption for DefaultFormatting {}
 
+/// This markers prevent Plotters to implement the default `Debug` based formatting
 pub struct NoDefaultFormatting;
 impl DefaultValueFormatOption for NoDefaultFormatting {}
 
+/// Determine how we can format a value in a coordinate system by default
 pub trait ValueFormatter<V> {
+    /// Format the value
     fn format(value: &V) -> String;
 }
 
+// By default the value is formatted by the debug trait
 impl<R: Ranged<FormatOption = DefaultFormatting>> ValueFormatter<R::ValueType> for R
 where
     R::ValueType: Debug,