Facts and Charts: Add more PHPDoc coverage

Summary: Make things a bit easier to understand.

Test Plan: Check parameters and return values for types and classes.

Reviewers: O1 Blessed Committers, Cigaryno, valerio.bozzolan

Reviewed By: O1 Blessed Committers, Cigaryno, valerio.bozzolan

Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno

Differential Revision: https://we.phorge.it/D25906

src/applications/fact/chart/PhabricatorChartDataQuery.php

@@ -7,6 +7,9 @@ final class PhabricatorChartDataQuery
   private $minimumValue;
   private $maximumValue;
 
+  /**
+   * @param int $minimum_value Epoch timestamp of the first input data
+   */
   public function setMinimumValue($minimum_value) {
     $this->minimumValue = $minimum_value;
     return $this;
@@ -16,6 +19,9 @@ final class PhabricatorChartDataQuery
     return $this->minimumValue;
   }
 
+  /**
+   * @param int $maximum_value Epoch timestamp of the last input data
+   */
   public function setMaximumValue($maximum_value) {
     $this->maximumValue = $maximum_value;
     return $this;
@@ -25,6 +31,10 @@ final class PhabricatorChartDataQuery
     return $this->maximumValue;
   }
 
+  /**
+   * @param int $limit Maximum amount of data points to handle. If there are
+   *   more data points, some in-between data will be ignored.
+   */
   public function setLimit($limit) {
     $this->limit = $limit;
     return $this;
@@ -34,6 +44,13 @@ final class PhabricatorChartDataQuery
     return $this->limit;
   }
 
+  /**
+   * Filter input data: Remove values lower resp. higher than the minimum
+   * resp. maximum values; remove some data if amount of data above the limit.
+   *
+   * @param array<int> $xv Epoch timestamps of unfitlered input data
+   * @return array<int> Epoch timestamps of fitlered input data
+   */
   public function selectInputValues(array $xv) {
     $result = array();
 

src/applications/fact/chart/PhabricatorChartDataset.php

@@ -13,6 +13,9 @@ abstract class PhabricatorChartDataset
     return $this->functions;
   }
 
+  /**
+   * @param array<PhabricatorComposeChartFunction> $functions
+   */
   final public function setFunctions(array $functions) {
     assert_instances_of($functions, 'PhabricatorComposeChartFunction');
 
@@ -67,7 +70,10 @@ abstract class PhabricatorChartDataset
   abstract protected function newChartDisplayData(
     PhabricatorChartDataQuery $data_query);
 
-
+  /**
+   * @param PhabricatorChartDataQuery $data_query
+   * @return PhabricatorChartDisplayData
+   */
   final public function getTabularDisplayData(
     PhabricatorChartDataQuery $data_query) {
     $results = array();

src/applications/fact/chart/PhabricatorChartFunction.php

@@ -10,6 +10,12 @@ abstract class PhabricatorChartFunction
     return $this->getPhobjectClassConstant('FUNCTIONKEY', 32);
   }
 
+  /**
+   * Get all available PhabricatorChartFunction subclasses
+   *
+   * @return array<PhabricatorChartFunction> All Phabricator*ChartFunction
+   *         classes which implement getFunctionKey()
+   */
   final public static function getAllFunctions() {
     return id(new PhutilClassMapQuery())
       ->setAncestorClass(__CLASS__)
@@ -127,6 +133,11 @@ abstract class PhabricatorChartFunction
     return $results;
   }
 
+  /**
+   * Return arrays of x,y data points for a two-dimensional chart
+   * @param PhabricatorChartDataQuery $query
+   * @return array<array<int,int>> x => epoch value; y => incremental number
+   */
   public function newDatapoints(PhabricatorChartDataQuery $query) {
     $xv = $this->newInputValues($query);
 

src/applications/fact/chart/PhabricatorChartStackedAreaDataset.php

@@ -7,6 +7,12 @@ final class PhabricatorChartStackedAreaDataset
 
   private $stacks;
 
+  /**
+   * @param array<array> $stacks One or more arrays with
+   *   PhabricatorChartFunctionLabel names of each PhabricatorChartFunction,
+   *   grouped by stacking
+   *   (e.g. [["created","reopened","moved-in"],["closed","moved-out"]])
+   */
   public function setStacks(array $stacks) {
     $this->stacks = $stacks;
     return $this;
@@ -16,6 +22,10 @@ final class PhabricatorChartStackedAreaDataset
     return $this->stacks;
   }
 
+  /**
+   * @param PhabricatorChartDataQuery $data_query
+   * @return PhabricatorChartDisplayData
+   */
   protected function newChartDisplayData(
     PhabricatorChartDataQuery $data_query) {
 
@@ -211,6 +221,10 @@ final class PhabricatorChartStackedAreaDataset
     return $must_define;
   }
 
+  /**
+   * @param PhabricatorChartDataQuery $data_query
+   * @param array<PhabricatorChartFunction> $functions
+   */
   private function getFunctionDatapoints(
     PhabricatorChartDataQuery $data_query,
     array $functions) {
@@ -231,6 +245,14 @@ final class PhabricatorChartStackedAreaDataset
     return $points;
   }
 
+  /**
+   * @param PhabricatorChartDataQuery $data_query
+   * @param array<string<epoch<string:int,string:int>>> $point_lists The key is
+   *   the stack (the PhabricatorChartFunctionLabel name of the
+   *   PhabricatorChartFunction (e.g. "created" or "moved-in")) and its value
+   *   is an array of keys which are date epochs and their values are another
+   *   array of x:date epoch and y:incremental integer pairs.
+   */
   private function getGeometry(
     PhabricatorChartDataQuery $data_query,
     array $point_lists) {

src/applications/fact/engine/PhabricatorChartEngine.php

@@ -45,6 +45,10 @@ abstract class PhabricatorChartEngine
     return clone id($engine_map[$engine_key]);
   }
 
+  /**
+   * Load all available chart engines.
+   * @return list<PhabricatorChartEngine> All available chart engines.
+   */
   final public static function getAllChartEngines() {
     return id(new PhutilClassMapQuery())
       ->setAncestorClass(__CLASS__)

src/applications/fact/engine/PhabricatorChartRenderingEngine.php

@@ -25,6 +25,11 @@ final class PhabricatorChartRenderingEngine
     return $this->chart;
   }
 
+  /**
+   * Load the chart by its key
+   * @param string $chart_key 12-character string identifier of chart to load
+   * @return PhabricatorFactChart
+   */
   public function loadChart($chart_key) {
     $chart = id(new PhabricatorFactChart())->loadOneWhere(
       'chartKey = %s',
@@ -37,12 +42,20 @@ final class PhabricatorChartRenderingEngine
     return $chart;
   }
 
+  /**
+   * Get the relative URI of the chart
+   * @param string $chart_key 12-character string identifier of chart to load
+   * @return string Relative URI of the chart, e.g. "fact/chart/a1b2c3d4e5f6/"
+   */
   public static function getChartURI($chart_key) {
     return id(new PhabricatorFactChart())
       ->setChartKey($chart_key)
       ->getURI();
   }
 
+  /**
+   * @return PhabricatorFactChart
+   */
   public function getStoredChart() {
     if (!$this->storedChart) {
       $chart = $this->getChart();
@@ -84,6 +97,9 @@ final class PhabricatorChartRenderingEngine
     return $this->storedChart;
   }
 
+  /**
+   * @return PhutilSafeHTML
+   */
   public function newChartView() {
     $chart = $this->getStoredChart();
     $chart_key = $chart->getChartKey();

src/applications/fact/engine/PhabricatorFactEngine.php

@@ -11,11 +11,20 @@ abstract class PhabricatorFactEngine extends Phobject {
       ->execute();
   }
 
+  /**
+   * @return array All types of facts known by this FactEngine
+   */
   abstract public function newFacts();
 
+  /**
+   * @return bool
+   */
   abstract public function supportsDatapointsForObject(
     PhabricatorLiskDAO $object);
 
+  /**
+   * Add new datapoints (due to a transaction) about an object
+   */
   abstract public function newDatapointsForObject(PhabricatorLiskDAO $object);
 
   final protected function getFact($key) {

src/applications/fact/engine/PhabricatorManiphestTaskFactEngine.php

@@ -3,6 +3,9 @@
 final class PhabricatorManiphestTaskFactEngine
   extends PhabricatorTransactionFactEngine {
 
+  /**
+   * @return array<PhabricatorCountFact> All known task related facts
+   */
   public function newFacts() {
     return array(
       id(new PhabricatorCountFact())

src/applications/fact/storage/PhabricatorFactIntDatapoint.php

@@ -49,6 +49,9 @@ final class PhabricatorFactIntDatapoint extends PhabricatorFactDAO {
     return $this->objectPHID;
   }
 
+  /**
+   * @param string $dimension_phid
+   */
   public function setDimensionPHID($dimension_phid) {
     $this->dimensionPHID = $dimension_phid;
     return $this;

src/applications/project/chart/PhabricatorProjectBurndownChartEngine.php

@@ -5,6 +5,9 @@ final class PhabricatorProjectBurndownChartEngine
 
   const CHARTENGINEKEY = 'project.burndown';
 
+  /**
+   * @param array<PhabricatorProject> $projects
+   */
   public function setProjects(array $projects) {
     assert_instances_of($projects, 'PhabricatorProject');
     $project_phids = mpull($projects, 'getPHID');
@@ -97,6 +100,11 @@ final class PhabricatorProjectBurndownChartEngine
     $chart->attachDatasets($datasets);
   }
 
+  /**
+   * @param string $fact_key The key of the new fact sum
+   *   (e.g. "tasks.open-count.assign.project")
+   * @param array<string> Project PHIDs
+   */
   private function newFactSum($fact_key, array $phids) {
     $result = array();
     $result[] = 'sum';