@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
Misc PhpDoc additions or improvements
Summary: Side effect of stuff I've been poking and trying to understand what it may do.
Test Plan: Check parameter and return types, e.g. via gettype() or get_class().
Reviewers: O1 Blessed Committers, mainframe98
Reviewed By: O1 Blessed Committers, mainframe98
Subscribers: mainframe98, tobiaswiese, valerio.bozzolan, Matthew, Cigaryno
Differential Revision: https://we.phorge.it/D26100
+198
-2
+18
src/applications/conduit/method/ConduitAPIMethod.php
+18
src/applications/conduit/method/ConduitAPIMethod.php
···
69
69
->setContent($box_view);
70
70
}
71
71
72
+
/**
73
+
* @return array Pairs of parameter name and their type
74
+
*/
72
75
abstract protected function defineParamTypes();
76
+
77
+
/**
78
+
* @return string Human-readable text description of the return format,
79
+
* for example 'array<string,mixed> | null'
80
+
*/
73
81
abstract protected function defineReturnType();
74
82
83
+
/**
84
+
* @return array Pairs of error code and the corresponding error message
85
+
*/
75
86
protected function defineErrorTypes() {
76
87
return array();
77
88
}
···
94
105
return $types;
95
106
}
96
107
108
+
/**
109
+
* @return string Human-readable text description of the return format,
110
+
* for example 'array<string,mixed> | null'
111
+
*/
97
112
public function getReturnType() {
98
113
return $this->defineReturnType();
99
114
}
100
115
116
+
/**
117
+
* @return array Pairs of error code and the corresponding error message
118
+
*/
101
119
public function getErrorTypes() {
102
120
return $this->defineErrorTypes();
103
121
}
+6
src/applications/diffusion/xaction/DiffusionCommitAcceptTransaction.php
+6
src/applications/diffusion/xaction/DiffusionCommitAcceptTransaction.php
···
14
14
return pht('This commit will be approved.');
15
15
}
16
16
17
+
/**
18
+
* @return string Transaction icon
19
+
*/
17
20
public function getIcon() {
18
21
return 'fa-check-circle-o';
19
22
}
20
23
24
+
/**
25
+
* @return string Transaction color
26
+
*/
21
27
public function getColor() {
22
28
return 'green';
23
29
}
+6
src/applications/diffusion/xaction/DiffusionCommitConcernTransaction.php
+6
src/applications/diffusion/xaction/DiffusionCommitConcernTransaction.php
···
14
14
return pht('This commit will be returned to the author for consideration.');
15
15
}
16
16
17
+
/**
18
+
* @return string Transaction icon
19
+
*/
17
20
public function getIcon() {
18
21
return 'fa-times-circle-o';
19
22
}
20
23
24
+
/**
25
+
* @return string Transaction color
26
+
*/
21
27
public function getColor() {
22
28
return 'red';
23
29
}
+6
src/applications/diffusion/xaction/DiffusionCommitResignTransaction.php
+6
src/applications/diffusion/xaction/DiffusionCommitResignTransaction.php
···
14
14
return pht('You will resign as an auditor for this commit.');
15
15
}
16
16
17
+
/**
18
+
* @return string Transaction icon
19
+
*/
17
20
public function getIcon() {
18
21
return 'fa-flag';
19
22
}
20
23
24
+
/**
25
+
* @return string Transaction color
26
+
*/
21
27
public function getColor() {
22
28
return 'orange';
23
29
}
+6
src/applications/diffusion/xaction/DiffusionCommitVerifyTransaction.php
+6
src/applications/diffusion/xaction/DiffusionCommitVerifyTransaction.php
···
19
19
return DiffusionCommitEditEngine::ACTIONGROUP_COMMIT;
20
20
}
21
21
22
+
/**
23
+
* @return string Transaction icon
24
+
*/
22
25
public function getIcon() {
23
26
return 'fa-refresh';
24
27
}
25
28
29
+
/**
30
+
* @return string Transaction color
31
+
*/
26
32
public function getColor() {
27
33
return 'indigo';
28
34
}
+4
src/applications/flag/conduit/FlagConduitAPIMethod.php
+4
src/applications/flag/conduit/FlagConduitAPIMethod.php
···
14
14
$flag->attachHandle($handle);
15
15
}
16
16
17
+
/**
18
+
* @param PhabricatorFlag $flag
19
+
* @return array<string,mixed>
20
+
*/
17
21
protected function buildFlagInfoDictionary($flag) {
18
22
$color = $flag->getColor();
19
23
$uri = PhabricatorEnv::getProductionURI($flag->getHandle()->getURI());
+4
src/applications/flag/conduit/FlagDeleteConduitAPIMethod.php
+4
src/applications/flag/conduit/FlagDeleteConduitAPIMethod.php
+7
src/applications/herald/action/HeraldAction.php
+7
src/applications/herald/action/HeraldAction.php
···
20
20
const DO_STANDARD_WRONG_RULE_TYPE = 'do.standard.wrong-rule-type';
21
21
const DO_STANDARD_FORBIDDEN = 'do.standard.forbidden';
22
22
23
+
/**
24
+
* @return string Text of option in first dropdown of a Herald Action
25
+
*/
23
26
abstract public function getHeraldActionName();
24
27
abstract public function supportsObject($object);
25
28
abstract public function supportsRuleType($rule_type);
26
29
abstract public function applyEffect($object, HeraldEffect $effect);
27
30
31
+
/**
32
+
* @return string|PhutilSafeHTML Description of the action performed by a
33
+
* Herald rule, shown under 'Take these actions...' on a Herald rule page
34
+
*/
28
35
abstract public function renderActionDescription($value);
29
36
30
37
public function getRequiredAdapterStates() {
+3
src/applications/herald/field/HeraldField.php
+3
src/applications/herald/field/HeraldField.php
···
13
13
const STANDARD_PHID_BOOL = 'standard.phid.bool';
14
14
const STANDARD_PHID_NULLABLE = 'standard.phid.nullable';
15
15
16
+
/**
17
+
* @return string Text of option in first dropdown of a Herald Condition
18
+
*/
16
19
abstract public function getHeraldFieldName();
17
20
abstract public function getHeraldFieldValue($object);
18
21
+6
src/applications/search/controller/PhabricatorSearchController.php
+6
src/applications/search/controller/PhabricatorSearchController.php
···
9
9
return true;
10
10
}
11
11
12
+
/**
13
+
* @return PhabricatorStandardPageView|AphrontRedirectResponse
14
+
*/
12
15
public function handleRequest(AphrontRequest $request) {
13
16
$viewer = $this->getViewer();
14
17
$query = $request->getStr('query');
···
96
99
return $this->delegateToController($controller);
97
100
}
98
101
102
+
/**
103
+
* @return AphrontSideNavFilterView
104
+
*/
99
105
public function buildSideNavView($for_app = false) {
100
106
$viewer = $this->getViewer();
101
107
+17
src/applications/search/engine/PhabricatorApplicationSearchEngine.php
+17
src/applications/search/engine/PhabricatorApplicationSearchEngine.php
···
36
36
return $this;
37
37
}
38
38
39
+
/**
40
+
* @return PhabricatorController
41
+
*/
39
42
public function getController() {
40
43
return $this->controller;
41
44
}
···
51
54
return $controller->delegateToController($search);
52
55
}
53
56
57
+
/**
58
+
* @return object|null Matching object (e.g. PhabricatorUser, PhamePost, or
59
+
* PhabricatorDashboardPanel), or null if no object matches.
60
+
*/
54
61
public function newResultObject() {
55
62
// We may be able to get this automatically if newQuery() is implemented.
56
63
$query = $this->newQuery();
···
73
80
return $this;
74
81
}
75
82
83
+
/**
84
+
* @return PhabricatorUser
85
+
* @throws PhutilInvalidStateException
86
+
*/
76
87
protected function requireViewer() {
77
88
if (!$this->viewer) {
78
89
throw new PhutilInvalidStateException('setViewer');
···
89
100
return ($this->context == self::CONTEXT_PANEL);
90
101
}
91
102
103
+
/**
104
+
* @param array<PHUIListItemView> $navigation_items
105
+
*/
92
106
public function setNavigationItems(array $navigation_items) {
93
107
assert_instances_of($navigation_items, 'PHUIListItemView');
94
108
$this->navigationItems = $navigation_items;
95
109
return $this;
96
110
}
97
111
112
+
/**
113
+
* @return array<PHUIListItemView> $navigation_items
114
+
*/
98
115
public function getNavigationItems() {
99
116
return $this->navigationItems;
100
117
}
+17
src/applications/search/engine/PhabricatorSearchNgramEngine.php
+17
src/applications/search/engine/PhabricatorSearchNgramEngine.php
···
3
3
final class PhabricatorSearchNgramEngine
4
4
extends Phobject {
5
5
6
+
/**
7
+
* @param string $value
8
+
* @return array<string>
9
+
*/
6
10
public function tokenizeNgramString($value) {
7
11
$value = trim($value, ' ');
8
12
$value = preg_split('/\s+/u', $value);
9
13
return $value;
10
14
}
11
15
16
+
/**
17
+
* @param string $string
18
+
* @return array<string>
19
+
*/
12
20
public function getTermNgramsFromString($string) {
13
21
return $this->getNgramsFromString($string, true);
14
22
}
15
23
24
+
/**
25
+
* @param string $string
26
+
* @return array<string>
27
+
*/
16
28
public function getSubstringNgramsFromString($string) {
17
29
return $this->getNgramsFromString($string, false);
18
30
}
19
31
32
+
/**
33
+
* @param string $value
34
+
* @param bool $as_term
35
+
* @return array<string>
36
+
*/
20
37
private function getNgramsFromString($value, $as_term) {
21
38
$value = phutil_utf8_strtolower($value);
22
39
$tokens = $this->tokenizeNgramString($value);
+3
src/applications/search/view/PhabricatorApplicationSearchResultView.php
+3
src/applications/search/view/PhabricatorApplicationSearchResultView.php
+8
src/applications/settings/editor/PhabricatorSettingsEditEngine.php
+8
src/applications/settings/editor/PhabricatorSettingsEditEngine.php
···
9
9
private $profileURI;
10
10
private $settingsPanel;
11
11
12
+
/**
13
+
* @param bool $is_self_edit True if the current viewer edits their own
14
+
* settings; false if someone else's (e.g. a bot account's settings).
15
+
*/
12
16
public function setIsSelfEdit($is_self_edit) {
13
17
$this->isSelfEdit = $is_self_edit;
14
18
return $this;
15
19
}
16
20
21
+
/**
22
+
* @return bool $is_self_edit True if the current viewer edits their own
23
+
* settings; false if someone else's (e.g. a bot account's settings).
24
+
*/
17
25
public function getIsSelfEdit() {
18
26
return $this->isSelfEdit;
19
27
}
+31
-2
src/applications/typeahead/datasource/PhabricatorTypeaheadDatasource.php
+31
-2
src/applications/typeahead/datasource/PhabricatorTypeaheadDatasource.php
···
98
98
return $this->phase;
99
99
}
100
100
101
+
/**
102
+
* @return string A text URI consisting of '/typeahead/class/' followed by
103
+
* a datasource (e.g. 'PhabricatorProjectDatasource/') and optionally
104
+
* URI parameters (e.g. '?parameters=%7B%22autocomplete%22%3A1%7D')
105
+
*/
101
106
public function getDatasourceURI() {
102
107
$params = $this->newURIParameters();
103
108
$uri = new PhutilURI('/typeahead/class/'.get_class($this).'/', $params);
104
109
return phutil_string_cast($uri);
105
110
}
106
111
112
+
/**
113
+
* @return string|null A text URI consisting of '/typeahead/browse/' followed
114
+
* by a datasource (e.g. 'PhabricatorPeopleDatasource/') and optionally
115
+
* URI parameters. Returns null if not browsable.
116
+
*/
107
117
public function getBrowseURI() {
108
118
if (!$this->isBrowsable()) {
109
119
return null;
···
114
124
return phutil_string_cast($uri);
115
125
}
116
126
127
+
/**
128
+
* @return array Array with key 'parameters' and value consisting of JSON
129
+
* encoded parameters.
130
+
*/
117
131
private function newURIParameters() {
118
132
if (!$this->parameters) {
119
133
return array();
···
126
140
return $map;
127
141
}
128
142
143
+
/**
144
+
* @return string Placeholder text to display in the empty datasource field
145
+
* field to provide a hint to the user, for example 'Type a user'
146
+
*/
129
147
abstract public function getPlaceholderText();
130
148
149
+
/**
150
+
* @return string Title to display in the selection popup dialog created
151
+
* after selecting the magnifier icon, for example 'Browse Projects'
152
+
*/
131
153
public function getBrowseTitle() {
132
154
return get_class($this);
133
155
}
···
136
158
abstract public function loadResults();
137
159
138
160
/**
139
-
* @param $phase string
140
-
* @param $limit int
161
+
* @param string $phase
162
+
* @param int $limit
141
163
*/
142
164
protected function loadResultsForPhase($phase, $limit) {
143
165
// By default, sources just load all of their results in every phase and
···
150
172
return $results;
151
173
}
152
174
175
+
/**
176
+
* @return array<string>
177
+
*/
153
178
public static function tokenizeString($string) {
154
179
$string = phutil_utf8_strtolower($string);
155
180
$string = trim($string);
···
475
500
476
501
477
502
/**
503
+
* @param string $token
504
+
* @return bool
478
505
* @task functions
479
506
*/
480
507
public static function isFunctionToken($token) {
···
589
616
590
617
591
618
/**
619
+
* @return array
592
620
* @task functions
593
621
*/
594
622
public function getFunctionStack() {
···
597
625
598
626
599
627
/**
628
+
* @return array<PhabricatorTypeaheadTokenView>
600
629
* @task functions
601
630
*/
602
631
protected function getCurrentFunction() {
+3
src/infrastructure/export/field/PhabricatorDoubleExportField.php
+3
src/infrastructure/export/field/PhabricatorDoubleExportField.php
+3
src/infrastructure/export/field/PhabricatorEpochExportField.php
+3
src/infrastructure/export/field/PhabricatorEpochExportField.php
+3
src/infrastructure/export/field/PhabricatorExportField.php
+3
src/infrastructure/export/field/PhabricatorExportField.php
+3
src/infrastructure/export/field/PhabricatorIDExportField.php
+3
src/infrastructure/export/field/PhabricatorIDExportField.php
+3
src/infrastructure/export/field/PhabricatorIntExportField.php
+3
src/infrastructure/export/field/PhabricatorIntExportField.php
+3
src/infrastructure/export/field/PhabricatorOptionExportField.php
+3
src/infrastructure/export/field/PhabricatorOptionExportField.php
+6
src/infrastructure/query/policy/PhabricatorCursorPagedPolicyAwareQuery.php
+6
src/infrastructure/query/policy/PhabricatorCursorPagedPolicyAwareQuery.php
···
1149
1149
1150
1150
1151
1151
/**
1152
+
* @return array<string,array<string,string>> PhutilKeyValueCacheStack string
1153
+
* (e.g. 'id', 'rank', 'fulltext-created', 'fulltext-modified') and the
1154
+
* cache value as an array, for example '{"table":"user","column":"id",
1155
+
* "reverse":false,"type":"int","unique":true}' or '{"table":null,
1156
+
* "column":"_ft_rank","type":"int","requires-ferret":true,"having":true}'
1152
1157
* @task order
1153
1158
*/
1154
1159
public function getOrderableColumns() {
···
1250
1255
}
1251
1256
1252
1257
/**
1258
+
* @return PhabricatorQueryOrderVector
1253
1259
* @task order
1254
1260
*/
1255
1261
private function getQueryableOrderVector() {
+7
src/view/AphrontTagView.php
+7
src/view/AphrontTagView.php
···
14
14
private $mustCapture;
15
15
private $workflow;
16
16
17
+
/**
18
+
* @param bool $workflow
19
+
* @return $this
20
+
*/
17
21
public function setWorkflow($workflow) {
18
22
$this->workflow = $workflow;
19
23
return $this;
20
24
}
21
25
26
+
/**
27
+
* @return bool
28
+
*/
22
29
public function getWorkflow() {
23
30
return $this->workflow;
24
31
}
+6
src/view/form/control/PhabricatorRemarkupControl.php
+6
src/view/form/control/PhabricatorRemarkupControl.php
···
13
13
return $this;
14
14
}
15
15
16
+
/**
17
+
* Set whether the form can be pinned on the screen
18
+
* @param bool $can_pin True if the form can be pinned on the screen by the
19
+
* user
20
+
* @return $this
21
+
*/
16
22
public function setCanPin($can_pin) {
17
23
$this->canPin = $can_pin;
18
24
return $this;
+4
src/view/layout/PhabricatorActionView.php
+4
src/view/layout/PhabricatorActionView.php
+4
src/view/phui/PHUICrumbView.php
+4
src/view/phui/PHUICrumbView.php
+7
src/view/phui/PHUIInfoView.php
+7
src/view/phui/PHUIInfoView.php
···
30
30
return $this;
31
31
}
32
32
33
+
/**
34
+
* @param string One of the SEVERITY_* constants defined in PHUIInfoView
35
+
* @return $this
36
+
*/
33
37
public function setSeverity($severity) {
34
38
$this->severity = $severity;
35
39
return $this;
36
40
}
37
41
42
+
/**
43
+
* @return string One of the SEVERITY_* constants defined in PHUIInfoView
44
+
*/
38
45
private function getSeverity() {
39
46
$severity = $this->severity ? $this->severity : self::SEVERITY_ERROR;
40
47
return $severity;