@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
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
+100
-1
+17
src/applications/fact/chart/PhabricatorChartDataQuery.php
+17
src/applications/fact/chart/PhabricatorChartDataQuery.php
···
7
7
private $minimumValue;
8
8
private $maximumValue;
9
9
10
+
/**
11
+
* @param int $minimum_value Epoch timestamp of the first input data
12
+
*/
10
13
public function setMinimumValue($minimum_value) {
11
14
$this->minimumValue = $minimum_value;
12
15
return $this;
···
16
19
return $this->minimumValue;
17
20
}
18
21
22
+
/**
23
+
* @param int $maximum_value Epoch timestamp of the last input data
24
+
*/
19
25
public function setMaximumValue($maximum_value) {
20
26
$this->maximumValue = $maximum_value;
21
27
return $this;
···
25
31
return $this->maximumValue;
26
32
}
27
33
34
+
/**
35
+
* @param int $limit Maximum amount of data points to handle. If there are
36
+
* more data points, some in-between data will be ignored.
37
+
*/
28
38
public function setLimit($limit) {
29
39
$this->limit = $limit;
30
40
return $this;
···
34
44
return $this->limit;
35
45
}
36
46
47
+
/**
48
+
* Filter input data: Remove values lower resp. higher than the minimum
49
+
* resp. maximum values; remove some data if amount of data above the limit.
50
+
*
51
+
* @param array<int> $xv Epoch timestamps of unfitlered input data
52
+
* @return array<int> Epoch timestamps of fitlered input data
53
+
*/
37
54
public function selectInputValues(array $xv) {
38
55
$result = array();
39
56
+7
-1
src/applications/fact/chart/PhabricatorChartDataset.php
+7
-1
src/applications/fact/chart/PhabricatorChartDataset.php
···
13
13
return $this->functions;
14
14
}
15
15
16
+
/**
17
+
* @param array<PhabricatorComposeChartFunction> $functions
18
+
*/
16
19
final public function setFunctions(array $functions) {
17
20
assert_instances_of($functions, 'PhabricatorComposeChartFunction');
18
21
···
67
70
abstract protected function newChartDisplayData(
68
71
PhabricatorChartDataQuery $data_query);
69
72
70
-
73
+
/**
74
+
* @param PhabricatorChartDataQuery $data_query
75
+
* @return PhabricatorChartDisplayData
76
+
*/
71
77
final public function getTabularDisplayData(
72
78
PhabricatorChartDataQuery $data_query) {
73
79
$results = array();
+11
src/applications/fact/chart/PhabricatorChartFunction.php
+11
src/applications/fact/chart/PhabricatorChartFunction.php
···
10
10
return $this->getPhobjectClassConstant('FUNCTIONKEY', 32);
11
11
}
12
12
13
+
/**
14
+
* Get all available PhabricatorChartFunction subclasses
15
+
*
16
+
* @return array<PhabricatorChartFunction> All Phabricator*ChartFunction
17
+
* classes which implement getFunctionKey()
18
+
*/
13
19
final public static function getAllFunctions() {
14
20
return id(new PhutilClassMapQuery())
15
21
->setAncestorClass(__CLASS__)
···
127
133
return $results;
128
134
}
129
135
136
+
/**
137
+
* Return arrays of x,y data points for a two-dimensional chart
138
+
* @param PhabricatorChartDataQuery $query
139
+
* @return array<array<int,int>> x => epoch value; y => incremental number
140
+
*/
130
141
public function newDatapoints(PhabricatorChartDataQuery $query) {
131
142
$xv = $this->newInputValues($query);
132
143
+22
src/applications/fact/chart/PhabricatorChartStackedAreaDataset.php
+22
src/applications/fact/chart/PhabricatorChartStackedAreaDataset.php
···
7
7
8
8
private $stacks;
9
9
10
+
/**
11
+
* @param array<array> $stacks One or more arrays with
12
+
* PhabricatorChartFunctionLabel names of each PhabricatorChartFunction,
13
+
* grouped by stacking
14
+
* (e.g. [["created","reopened","moved-in"],["closed","moved-out"]])
15
+
*/
10
16
public function setStacks(array $stacks) {
11
17
$this->stacks = $stacks;
12
18
return $this;
···
16
22
return $this->stacks;
17
23
}
18
24
25
+
/**
26
+
* @param PhabricatorChartDataQuery $data_query
27
+
* @return PhabricatorChartDisplayData
28
+
*/
19
29
protected function newChartDisplayData(
20
30
PhabricatorChartDataQuery $data_query) {
21
31
···
211
221
return $must_define;
212
222
}
213
223
224
+
/**
225
+
* @param PhabricatorChartDataQuery $data_query
226
+
* @param array<PhabricatorChartFunction> $functions
227
+
*/
214
228
private function getFunctionDatapoints(
215
229
PhabricatorChartDataQuery $data_query,
216
230
array $functions) {
···
231
245
return $points;
232
246
}
233
247
248
+
/**
249
+
* @param PhabricatorChartDataQuery $data_query
250
+
* @param array<string<epoch<string:int,string:int>>> $point_lists The key is
251
+
* the stack (the PhabricatorChartFunctionLabel name of the
252
+
* PhabricatorChartFunction (e.g. "created" or "moved-in")) and its value
253
+
* is an array of keys which are date epochs and their values are another
254
+
* array of x:date epoch and y:incremental integer pairs.
255
+
*/
234
256
private function getGeometry(
235
257
PhabricatorChartDataQuery $data_query,
236
258
array $point_lists) {
+4
src/applications/fact/engine/PhabricatorChartEngine.php
+4
src/applications/fact/engine/PhabricatorChartEngine.php
···
45
45
return clone id($engine_map[$engine_key]);
46
46
}
47
47
48
+
/**
49
+
* Load all available chart engines.
50
+
* @return list<PhabricatorChartEngine> All available chart engines.
51
+
*/
48
52
final public static function getAllChartEngines() {
49
53
return id(new PhutilClassMapQuery())
50
54
->setAncestorClass(__CLASS__)
+16
src/applications/fact/engine/PhabricatorChartRenderingEngine.php
+16
src/applications/fact/engine/PhabricatorChartRenderingEngine.php
···
25
25
return $this->chart;
26
26
}
27
27
28
+
/**
29
+
* Load the chart by its key
30
+
* @param string $chart_key 12-character string identifier of chart to load
31
+
* @return PhabricatorFactChart
32
+
*/
28
33
public function loadChart($chart_key) {
29
34
$chart = id(new PhabricatorFactChart())->loadOneWhere(
30
35
'chartKey = %s',
···
37
42
return $chart;
38
43
}
39
44
45
+
/**
46
+
* Get the relative URI of the chart
47
+
* @param string $chart_key 12-character string identifier of chart to load
48
+
* @return string Relative URI of the chart, e.g. "fact/chart/a1b2c3d4e5f6/"
49
+
*/
40
50
public static function getChartURI($chart_key) {
41
51
return id(new PhabricatorFactChart())
42
52
->setChartKey($chart_key)
43
53
->getURI();
44
54
}
45
55
56
+
/**
57
+
* @return PhabricatorFactChart
58
+
*/
46
59
public function getStoredChart() {
47
60
if (!$this->storedChart) {
48
61
$chart = $this->getChart();
···
84
97
return $this->storedChart;
85
98
}
86
99
100
+
/**
101
+
* @return PhutilSafeHTML
102
+
*/
87
103
public function newChartView() {
88
104
$chart = $this->getStoredChart();
89
105
$chart_key = $chart->getChartKey();
+9
src/applications/fact/engine/PhabricatorFactEngine.php
+9
src/applications/fact/engine/PhabricatorFactEngine.php
···
11
11
->execute();
12
12
}
13
13
14
+
/**
15
+
* @return array All types of facts known by this FactEngine
16
+
*/
14
17
abstract public function newFacts();
15
18
19
+
/**
20
+
* @return bool
21
+
*/
16
22
abstract public function supportsDatapointsForObject(
17
23
PhabricatorLiskDAO $object);
18
24
25
+
/**
26
+
* Add new datapoints (due to a transaction) about an object
27
+
*/
19
28
abstract public function newDatapointsForObject(PhabricatorLiskDAO $object);
20
29
21
30
final protected function getFact($key) {
+3
src/applications/fact/engine/PhabricatorManiphestTaskFactEngine.php
+3
src/applications/fact/engine/PhabricatorManiphestTaskFactEngine.php
+3
src/applications/fact/storage/PhabricatorFactIntDatapoint.php
+3
src/applications/fact/storage/PhabricatorFactIntDatapoint.php
+8
src/applications/project/chart/PhabricatorProjectBurndownChartEngine.php
+8
src/applications/project/chart/PhabricatorProjectBurndownChartEngine.php
···
5
5
6
6
const CHARTENGINEKEY = 'project.burndown';
7
7
8
+
/**
9
+
* @param array<PhabricatorProject> $projects
10
+
*/
8
11
public function setProjects(array $projects) {
9
12
assert_instances_of($projects, 'PhabricatorProject');
10
13
$project_phids = mpull($projects, 'getPHID');
···
97
100
$chart->attachDatasets($datasets);
98
101
}
99
102
103
+
/**
104
+
* @param string $fact_key The key of the new fact sum
105
+
* (e.g. "tasks.open-count.assign.project")
106
+
* @param array<string> Project PHIDs
107
+
*/
100
108
private function newFactSum($fact_key, array $phids) {
101
109
$result = array();
102
110
$result[] = 'sum';