Document chart usage

Author: shai-almog

CodenameOne/src/com/codename1/charts/views/BarChart.java

@@ -31,10 +31,30 @@
 import java.util.List;
 
 
-/**
- * The bar chart rendering class.
- */
-public class BarChart extends XYChart {
+/**
+ * Renders a bar chart based on an {@link XYMultipleSeriesDataset}.
+ * <p>
+ * Create an instance together with a matching {@link XYMultipleSeriesRenderer}
+ * and wrap it in a {@link com.codename1.charts.ChartComponent} to display it in
+ * the UI. A minimal setup looks like this:
+ *
+ * <pre>
+ * XYMultipleSeriesDataset dataset = new XYMultipleSeriesDataset();
+ * dataset.addSeries(mySeries);
+ *
+ * XYMultipleSeriesRenderer renderer = new XYMultipleSeriesRenderer();
+ * renderer.addSeriesRenderer(new XYSeriesRenderer());
+ *
+ * BarChart chart = new BarChart(dataset, renderer, BarChart.Type.DEFAULT);
+ * Form form = new Form(new BorderLayout());
+ * form.add(BorderLayout.CENTER, new ChartComponent(chart));
+ * form.show();
+ * </pre>
+ *
+ * The {@link Type} supplied to the constructor controls whether the bars are
+ * rendered in their default style, stacked or heaped.
+ */
+public class BarChart extends XYChart {
     /** The constant to identify this chart type. */
     public static final String TYPE = "Bar";
     /** The legend shape width. */

CodenameOne/src/com/codename1/charts/views/BubbleChart.java

@@ -27,10 +27,17 @@
 import java.util.List;
 
 
-/**
- * The bubble chart rendering class.
- */
-public class BubbleChart extends XYChart {
+/**
+ * Displays series of {@link XYValueSeries} entries as proportional bubbles on
+ * top of an {@link XYChart} plot.
+ * <p>
+ * Combine the chart with an {@link XYMultipleSeriesDataset} that contains one
+ * or more {@link XYValueSeries} instances and supply an
+ * {@link XYMultipleSeriesRenderer}. The resulting {@code BubbleChart} can be
+ * wrapped in a {@link com.codename1.charts.ChartComponent} to embed it inside a
+ * Codename One UI.
+ */
+public class BubbleChart extends XYChart {
     /** The constant to identify this chart type. */
     public static final String TYPE = "Bubble";
     /** The legend shape width. */

CodenameOne/src/com/codename1/charts/views/CombinedXYChart.java

@@ -28,10 +28,18 @@
 import java.util.List;
 
 
-/**
- * The combined XY chart rendering class.
- */
-public class CombinedXYChart extends XYChart {
+/**
+ * Aggregates multiple {@link XYChart} implementations into a single plot so
+ * different series can be visualised using different renderers (for example a
+ * line overlaid on top of a bar chart).
+ * <p>
+ * Provide the constructor with an {@link XYMultipleSeriesDataset}, a matching
+ * {@link XYMultipleSeriesRenderer} and an array of
+ * {@link XYCombinedChartDef} instances that describe which inner chart type
+ * should render each data series. The combined chart can then be wrapped in a
+ * {@link com.codename1.charts.ChartComponent} for display.
+ */
+public class CombinedXYChart extends XYChart {
 
     private final XYCombinedChartDef[] chartDefinitions;
 

CodenameOne/src/com/codename1/charts/views/CubicLineChart.java

@@ -27,10 +27,16 @@
 import java.util.List;
 
 
-/**
- * The interpolated (cubic) line chart rendering class.
- */
-public class CubicLineChart extends LineChart {
+/**
+ * Draws smooth curves through XY series values using cubic interpolation.
+ * <p>
+ * Use this chart when you want to emphasise the trend between points rather
+ * than the raw straight-line segments of {@link LineChart}. Supply the
+ * {@link XYMultipleSeriesDataset} and {@link XYMultipleSeriesRenderer} as usual
+ * and pass an optional smoothness factor to control how tightly the curve
+ * follows the provided data points.
+ */
+public class CubicLineChart extends LineChart {
     /** The chart type. */
     public static final String TYPE = "Cubic";
 

CodenameOne/src/com/codename1/charts/views/DialChart.java

@@ -26,10 +26,15 @@
 import com.codename1.ui.Component;
 
 
-/**
- * The dial chart rendering class.
- */
-public class DialChart extends RoundChart {
+/**
+ * Presents values from a {@link CategorySeries} as gauges on a dial.
+ * <p>
+ * Configure the dial appearance via a {@link DialRenderer} and supply both the
+ * dataset and renderer to the constructor. Dial charts are typically wrapped in
+ * a {@link com.codename1.charts.ChartComponent} so they can be placed inside
+ * regular Codename One layouts.
+ */
+public class DialChart extends RoundChart {
     /** The radius of the needle. */
     private static final int NEEDLE_RADIUS = 10;
     /** The series renderer. */

CodenameOne/src/com/codename1/charts/views/DoughnutChart.java

@@ -28,10 +28,16 @@
 import java.util.List;
 
 
-/**
- * The doughnut chart rendering class.
- */
-public class DoughnutChart extends RoundChart {
+/**
+ * Visualises a {@link MultipleCategorySeries} as concentric rings that share a
+ * common centre (also known as a doughnut chart).
+ * <p>
+ * Each category in the dataset is drawn as a separate ring, making it suitable
+ * for representing hierarchical proportions. Construct the chart with the
+ * dataset and a {@link DefaultRenderer} and wrap it in a
+ * {@link com.codename1.charts.ChartComponent} to place it on screen.
+ */
+public class DoughnutChart extends RoundChart {
     /** The series dataset. */
     private final MultipleCategorySeries mDataset;
     /** A step variable to control the size of the legend shape. */

CodenameOne/src/com/codename1/charts/views/LineChart.java

@@ -28,10 +28,15 @@
 import java.util.List;
 
 
-/**
- * The line chart rendering class.
- */
-public class LineChart extends XYChart {
+/**
+ * Plots series of X/Y points using straight line segments.
+ * <p>
+ * Supply the chart with an {@link XYMultipleSeriesDataset} and configure its
+ * appearance via an {@link XYMultipleSeriesRenderer}. The chart is commonly
+ * wrapped in a {@link com.codename1.charts.ChartComponent} before being added
+ * to a Codename One form.
+ */
+public class LineChart extends XYChart {
     /** The constant to identify this chart type. */
     public static final String TYPE = "Line";
     /** The legend shape width. */

CodenameOne/src/com/codename1/charts/views/PieChart.java

@@ -33,7 +33,11 @@
 
 
 /**
- * The pie chart rendering class.
+ * Shows each value from a {@link CategorySeries} as a slice of a circle.
+ * <p>
+ * Combine this chart with a {@link DefaultRenderer} to control colours, labels
+ * and gradients. The resulting {@code PieChart} can be embedded in a form via a
+ * {@link com.codename1.charts.ChartComponent}.
  */
 public class PieChart extends RoundChart {
     /** Handles returning values when tapping on PieChart. */

CodenameOne/src/com/codename1/charts/views/RadarChart.java

@@ -28,7 +28,13 @@
 import java.util.List;
 
 /**
- * The radar chart rendering class.
+ * Draws multi-dimensional data as a web chart (also known as a radar or spider
+ * chart).
+ * <p>
+ * The chart consumes an {@link AreaSeries} where each category represents an
+ * axis radiating from the centre. Configure colours and labelling through a
+ * {@link DefaultRenderer} and wrap the instance in a
+ * {@link com.codename1.charts.ChartComponent} to present it inside your UI.
  */
 public class RadarChart extends RoundChart {
 

CodenameOne/src/com/codename1/charts/views/RangeBarChart.java

@@ -26,10 +26,16 @@
 import java.util.List;
 
 
-/**
- * The range bar chart rendering class.
- */
-public class RangeBarChart extends BarChart {
+/**
+ * Extends {@link BarChart} to support values that represent ranges rather than
+ * single points. Each bar is drawn from the lower value to the upper value in
+ * the dataset.
+ * <p>
+ * Use this chart with an {@link XYMultipleSeriesDataset} containing
+ * {@link XYSeries} instances where consecutive entries form the minimum/maximum
+ * pair for a category.
+ */
+public class RangeBarChart extends BarChart {
     /** The chart type. */
     public static final String TYPE = "RangeBar";