MDL-55108 core: Document the charting library

Part of MDL-54987 epic.

lib/classes/chart_axis.php

@@ -38,46 +38,97 @@ use renderable;
  */
 class chart_axis implements JsonSerializable {
 
+    /** Default axis position. */
     const POS_DEFAULT = null;
+    /** Bottom axis position. */
     const POS_BOTTOM = 'bottom';
+    /** Left axis position. */
     const POS_LEFT = 'left';
+    /** Right axis position. */
     const POS_RIGHT = 'right';
+    /** Top axis position. */
     const POS_TOP = 'top';
 
+    /** @var string The axis label. */
     protected $label = null;
+    /** @var string[] The axis labels, tick values. */
     protected $labels = null;
+    /** @var float The maximum tick value. */
     protected $max = null;
+    /** @var float The minimum tick value. */
     protected $min = null;
+    /** @var string The axis position. */
     protected $position = self::POS_DEFAULT;
+    /** @var float The stepsize between ticks. */
     protected $stepsize = null;
 
+    /**
+     * Constructor.
+     *
+     * Must not take any argument.
+     */
     public function __construct() {
     }
 
+    /**
+     * Get the label.
+     *
+     * @return string
+     */
     public function get_label() {
         return $this->label;
     }
 
+    /**
+     * Get the labels.
+     *
+     * @return string[]
+     */
     public function get_labels() {
         return $this->labels;
     }
 
+    /**
+     * Get the max value.
+     *
+     * @return float
+     */
     public function get_max() {
         return $this->max;
     }
 
+    /**
+     * Get the min value.
+     *
+     * @return float
+     */
     public function get_min() {
         return $this->min;
     }
 
+    /**
+     * Get the axis position.
+     *
+     * @return string
+     */
     public function get_position() {
         return $this->position;
     }
 
+    /**
+     * Get the step size.
+     *
+     * @return float
+     */
     public function get_stepsize() {
         return $this->stepsize;
     }
 
+    /**
+     * Serialize the object.
+     *
+     * @return array
+     */
     public function jsonSerialize() {
         return [
             'label' => $this->label,
@@ -89,28 +140,58 @@ class chart_axis implements JsonSerializable {
         ];
     }
 
+    /**
+     * Set the label.
+     *
+     * @param string $label The label.
+     */
     public function set_label($label) {
-        return $this->label = $label;
+        $this->label = $label;
     }
 
+    /**
+     * Set the labels.
+     *
+     * @param string[] $labels The labels.
+     */
     public function set_labels($labels) {
-        return $this->labels = $labels;
+        $this->labels = $labels;
     }
 
+    /**
+     * Set the max value.
+     *
+     * @param float $max The max value.
+     */
     public function set_max($max) {
-        return $this->max = $max;
+        $this->max = $max;
     }
 
+    /**
+     * Set the min value.
+     *
+     * @param float $min The min value.
+     */
     public function set_min($min) {
-        return $this->min = $min;
+        $this->min = $min;
     }
 
+    /**
+     * Set the position.
+     *
+     * @param string $position Use constant self::POS_*.
+     */
     public function set_position($position) {
-        return $this->position = $position;
+        $this->position = $position;
     }
 
+    /**
+     * Set the step size.
+     *
+     * @param float $stepsize The step size.
+     */
     public function set_stepsize($stepsize) {
-        return $this->stepsize = $stepsize;
+        $this->stepsize = $stepsize;
     }
 
 }

lib/classes/chart_bar.php

@@ -34,6 +34,9 @@ defined('MOODLE_INTERNAL') || die();
  */
 class chart_bar extends chart_base {
 
+    /**
+     * Set the defaults.
+     */
     protected function set_defaults() {
         parent::set_defaults();
         $yaxis = $this->get_yaxis(0, true);

lib/classes/chart_base.php

@@ -38,20 +38,43 @@ use renderable;
  */
 class chart_base implements JsonSerializable, renderable {
 
+    /** @var chart_series[] The series constituting this chart. */
     protected $series = [];
+    /** @var string[] The labels for the X axis when categorised. */
     protected $labels = [];
+    /** @var string The title of the chart. */
     protected $title = null;
+    /** @var chart_axis[] The X axes. */
     protected $xaxes = [];
+    /** @var chart_axis[] The Y axes. */
     protected $yaxes = [];
 
+    /**
+     * Constructor.
+     *
+     * Must not take any argument.
+     *
+     * Most of the time you do not want to extend this, rather extend the
+     * method {@link self::set_defaults} to set the defaults on instantiation.
+     */
     public function __construct() {
         $this->set_defaults();
     }
 
+    /**
+     * Add a series to the chart.
+     *
+     * @param chart_series $serie The serie.
+     */
     public function add_series(chart_series $serie) {
         $this->series[] = $serie;
     }
 
+    /**
+     * Serialize the object.
+     *
+     * @return array
+     */
     public function jsonSerialize() {
         return [
             'type' => $this->get_type(),
@@ -65,6 +88,14 @@ class chart_base implements JsonSerializable, renderable {
         ];
     }
 
+    /**
+     * Get an axis.
+     *
+     * @param string $type Accepts values 'x' or 'y'.
+     * @param int $index The index of this axis.
+     * @param bool $createifnotexists Whether to create the axis if not found.
+     * @return chart_axis
+     */
     private function get_axis($type, $index, $createifnotexists) {
         $isx = $type === 'x';
         if ($isx) {
@@ -89,55 +120,134 @@ class chart_base implements JsonSerializable, renderable {
         return $axis;
     }
 
+    /**
+     * Get the labels of the X axis.
+     *
+     * @return string[]
+     */
     public function get_labels() {
         return $this->labels;
     }
 
+    /**
+     * Get the series.
+     *
+     * @return chart_series[]
+     */
     public function get_series() {
         return $this->series;
     }
 
+    /**
+     * Get the title.
+     *
+     * @return string
+     */
     public function get_title() {
         return $this->title;
     }
 
+    /**
+     * Get the chart type.
+     *
+     * @return string
+     */
     public function get_type() {
         $classname = get_class($this);
         return substr($classname, strpos($classname, '_') + 1);
     }
 
+    /**
+     * Get the X axes.
+     *
+     * @return chart_axis[]
+     */
     public function get_xaxes() {
         return $this->xaxes;
     }
 
+    /**
+     * Get an X axis.
+     *
+     * @param int $index The index of the axis.
+     * @param bool $createifnotexists When true, create an instance of the axis if none exist at this index yet.
+     * @return chart_axis
+     */
     public function get_xaxis($index = 0, $createifnotexists = false) {
         return $this->get_axis('x', $index, $createifnotexists);
     }
 
+    /**
+     * Get the Y axes.
+     *
+     * @return chart_axis[]
+     */
     public function get_yaxes() {
         return $this->yaxes;
     }
 
+    /**
+     * Get a Y axis.
+     *
+     * @param int $index The index of the axis.
+     * @param bool $createifnotexists When true, create an instance of the axis if none exist at this index yet.
+     * @return chart_axis
+     */
     public function get_yaxis($index = 0, $createifnotexists = false) {
         return $this->get_axis('y', $index, $createifnotexists);
     }
 
+    /**
+     * Set the defaults for this chart type.
+     *
+     * Child classes can extend this to set default values on instantiation.
+     *
+     * In general the constructor could be used, but this method is here to
+     * emphasize and self-document the default values set by the chart type.
+     *
+     * @return void
+     */
     protected function set_defaults() {
-        // For the child classes to extend.
     }
 
+    /**
+     * Set the chart labels.
+     *
+     * @param string[] $labels The labels.
+     */
     public function set_labels(array $labels) {
         $this->labels = $labels;
     }
 
+    /**
+     * Set the title.
+     *
+     * @param string $title The title.
+     */
     public function set_title($title) {
         $this->title = $title;
     }
 
+    /**
+     * Set an X axis.
+     *
+     * Note that this will override any predefined axis without warning.
+     *
+     * @param chart_axis $axis The axis.
+     * @param int $index The index of the axis.
+     */
     public function set_xaxis(chart_axis $axis, $index = 0) {
         return $this->xaxes[$index] = $axis;
     }
 
+    /**
+     * Set an Y axis.
+     *
+     * Note that this will override any predefined axis without warning.
+     *
+     * @param chart_axis $axis The axis.
+     * @param int $index The index of the axis.
+     */
     public function set_yaxis(chart_axis $axis, $index = 0) {
         return $this->yaxes[$index] = $axis;
     }

lib/classes/chart_series.php

@@ -37,39 +37,81 @@ use JsonSerializable;
  */
 class chart_series implements JsonSerializable {
 
+    /** Default type for a series. */
     const TYPE_DEFAULT = null;
+    /** Series of type line. */
     const TYPE_LINE = 'line';
 
+    /** @var string Color of the series. */
     protected $color;
+    /** @var string Label for this series. */
     protected $label;
+    /** @var string Type of the series. */
     protected $type = self::TYPE_DEFAULT;
+    /** @var float[] Values of the series. */
     protected $values = [];
 
+    /**
+     * Constructor.
+     *
+     * @param string $label The label of the series.
+     * @param float[] $values The values of this series.
+     */
     public function __construct($label, $values) {
         $this->values = $values;
         $this->label = $label;
     }
 
+    /**
+     * Get the color.
+     *
+     * @return string
+     */
     public function get_color() {
         return $this->color;
     }
 
+    /**
+     * Get the number of values in this series.
+     *
+     * @return int
+     */
     public function get_count() {
         return count($this->values);
     }
 
+    /**
+     * Get the label of the series.
+     *
+     * @return string
+     */
     public function get_label() {
         return $this->label;
     }
 
+    /**
+     * Get the type of series.
+     *
+     * @return string
+     */
     public function get_type() {
         return $this->type;
     }
 
+    /**
+     * Get the values of the series.
+     *
+     * @return [type]
+     */
     public function get_values() {
         return $this->values;
     }
 
+    /**
+     * Serialize the object.
+     *
+     * @return array
+     */
     public function jsonSerialize() {
         $data = [
             'label' => $this->label,
@@ -80,10 +122,20 @@ class chart_series implements JsonSerializable {
         return $data;
     }
 
+    /**
+     * Set the color of the series.
+     *
+     * @param string $color CSS compatible color.
+     */
     public function set_color($color) {
         $this->color = $color;
     }
 
+    /**
+     * Set the type of the series.
+     *
+     * @param string $type Constant value from self::TYPE_*.
+     */
     public function set_type($type) {
         if (!in_array($type, [self::TYPE_DEFAULT, self::TYPE_LINE])) {
             throw new coding_exception('Invalid serie type.');