@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
ManiphestReportController: Add more PHPDoc coverage
Summary: Make things a bit easier to understand, for the start.
Test Plan: Check return values for their types and classes.
Reviewers: O1 Blessed Committers, valerio.bozzolan
Reviewed By: O1 Blessed Committers, valerio.bozzolan
Subscribers: tobiaswiese, valerio.bozzolan, Matthew, Cigaryno
Differential Revision: https://we.phorge.it/D25901
+39
-3
+39
-3
src/applications/maniphest/controller/ManiphestReportController.php
+39
-3
src/applications/maniphest/controller/ManiphestReportController.php
···
72
72
}
73
73
74
74
/**
75
+
* Render the "Burnup Rate" on /maniphest/report/burn/.
76
+
*
77
+
* Ironically this is not called for the "Burndown" on /project/reports/$id/
78
+
* as that's handled by PhabricatorProjectReportsController instead.
79
+
*
75
80
* @return array<AphrontListFilterView, PHUIObjectBoxView>
76
81
*/
77
82
public function renderBurn() {
···
484
489
return array(array_keys($out), array_values($out));
485
490
}
486
491
492
+
/**
493
+
* @param $label string Time representation for the row, e.g. "Feb 29 2024",
494
+
* "All Time", "Week of May 10 2024", "Month To Date", etc.
495
+
* @param $info array<string,int> open|close; number of tasks in timespan
496
+
* @return array<string,string,string,PhutilSafeHTML> Row text label; number
497
+
* of open tasks as string; number of closed tasks as string;
498
+
* PhutilSafeHTML such as "<span class="red">+144</span>"
499
+
*/
487
500
private function formatBurnRow($label, $info) {
488
501
$delta = $info['open'] - $info['close'];
489
502
$fmt = number_format($delta);
···
502
515
);
503
516
}
504
517
518
+
/**
519
+
* @return int 50
520
+
*/
505
521
private function getAveragePriority() {
506
522
// TODO: This is sort of a hard-code for the default "normal" status.
507
523
// When reports are more powerful, this should be made more general.
508
524
return 50;
509
525
}
510
526
527
+
/**
528
+
* Render all table cells in the "Open Tasks" table on /maniphest/report/*.
529
+
*
530
+
* @return array<AphrontListFilterView,PHUIObjectBoxView>
531
+
*/
511
532
public function renderOpenTasks() {
512
533
$request = $this->getRequest();
513
534
$viewer = $request->getUser();
···
792
813
793
814
794
815
/**
795
-
* Load all the tasks that have been recently closed.
816
+
* Load all tasks that have been recently closed.
817
+
* This is used for the "Recently Closed" column on /maniphest/report/*.
818
+
*
819
+
* @return array<ManiphestTask|null>
796
820
*/
797
821
private function loadRecentlyClosedTasks() {
798
822
list($ignored, $window_epoch) = $this->getWindow();
···
845
869
}
846
870
847
871
/**
848
-
* Parse the "Recently Means" filter into:
849
-
*
872
+
* Parse the "Recently Means" filter on /maniphest/report/* into:
850
873
* - A string representation, like "12 AM 7 days ago" (default);
851
874
* - a locale-aware epoch representation; and
852
875
* - a possible error.
876
+
* This is used for the "Recently Closed" column on /maniphest/report/*.
877
+
*
878
+
* @return array<string,integer,string|null> "Recently Means" user input;
879
+
* Resulting epoch timeframe used to get "Recently Closed" numbers
880
+
* (when user input is invalid, it defaults to a week ago); "Invalid"
881
+
* if first parameter could not be parsed as an epoch, else null.
853
882
*/
854
883
private function getWindow() {
855
884
$request = $this->getRequest();
···
884
913
return array($window_str, $window_epoch, $error);
885
914
}
886
915
916
+
/**
917
+
* Render date of oldest open task per user or per project with a link.
918
+
* Used on /maniphest/report/user/ and /maniphest/report/project/ URIs.
919
+
*
920
+
* @return array<PhutilSafeHTML,int> HTML link markup and the timespan
921
+
* (as epoch) since task creation
922
+
*/
887
923
private function renderOldest(array $tasks) {
888
924
assert_instances_of($tasks, 'ManiphestTask');
889
925
$oldest = null;