Skip to content

Commit b024d2e

Browse files
danielbachhuberdanielbachhuber
committed
Include params in docs
1 parent a7286cf commit b024d2e

File tree

4 files changed

+197
-11
lines changed

4 files changed

+197
-11
lines changed

‎Phakefile.php‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,9 @@ function gen_cmd_pages( $cmd, $parent = array() ) {
138138
if ( ! isset( $function_groups[ $group_name ] ) ) {
139139
$function_groups[ $group_name ] = array();
140140
}
141+
if ( isset( $api['phpdoc']['parameters']['params'] ) ) {
142+
$api['params'] = $api['phpdoc']['parameters']['params'];
143+
}
141144
$function_groups[ $group_name ][] = $api;
142145
}
143146

@@ -147,6 +150,27 @@ function gen_cmd_pages( $cmd, $parent = array() ) {
147150
$out .= '## ' . $name . PHP_EOL . PHP_EOL;
148151
$out .= render( 'api-list.mustache', array( 'apis' => $functions ) );
149152
}
153+
154+
$class_groups = array();
155+
foreach( $apis as $api ) {
156+
if ( 'method' !== $api['type'] ) {
157+
continue;
158+
}
159+
$group_name = $api['class'];
160+
if ( ! isset( $class_groups[ $group_name ] ) ) {
161+
$class_groups[ $group_name ] = array();
162+
}
163+
if ( isset( $api['phpdoc']['parameters']['params'] ) ) {
164+
$api['params'] = $api['phpdoc']['parameters']['params'];
165+
}
166+
$class_groups[ $group_name ][] = $api;
167+
}
168+
169+
foreach( $class_groups as $name => $methods ) {
170+
$out .= '## ' . $name . PHP_EOL . PHP_EOL;
171+
$out .= render( 'api-list.mustache', array( 'apis' => $methods ) );
172+
}
173+
150174
file_put_contents( '_includes/api-list.html', $out );
151175
});
152176

‎_includes/api-list.html‎

Lines changed: 130 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,37 +3,160 @@
33
## WP_CLI\Utils
44

55

6-
### format_items
7-
86
```WP_CLI\Utils\format_items( $format, $items, $fields )```
97

108
Output items in a table, JSON, CSV, ids, or the total count
119

10+
<div>
11+
<strong>$format</strong> (string) Format to use: 'table', 'json', 'csv', 'ids', 'count'<br />
12+
<strong>$items</strong> (array) Data to output<br />
13+
<strong>$fields</strong> (array|string) Named fields for each item of data. Can be array or comma-separated list<br />
14+
15+
</div>
16+
17+
***
1218

13-
### write_csv
1419

1520
```WP_CLI\Utils\write_csv( $fd, $rows, $headers = array() )```
1621

1722
Write data as CSV to a given file.
1823

24+
<div>
25+
<strong>$fd</strong> (resource) File descriptor<br />
26+
<strong>$rows</strong> (array) Array of rows to output<br />
27+
<strong>$headers</strong> (array) List of CSV columns (optional)<br />
28+
29+
</div>
30+
31+
***
1932

20-
### get_named_sem_ver
2133

2234
```WP_CLI\Utils\get_named_sem_ver( $new_version, $original_version )```
2335

2436
Compare two version strings to get the named semantic version.
2537

38+
<div>
39+
<strong>$new_version</strong> (string) <br />
40+
<strong>$original_version</strong> (string) <br />
2641

27-
### get_flag_value
42+
<p><strong>@return</strong> string 'major', 'minor', 'patch'</p>
43+
</div>
44+
45+
***
2846

29-
```WP_CLI\Utils\get_flag_value( $args, $flag, $default = array() )```
47+
48+
```WP_CLI\Utils\get_flag_value( $assoc_args, $flag, $default = array() )```
3049

3150
Return the flag value or, if it's not set, the $default value.
3251

52+
<div>
53+
<strong>$assoc_args</strong> (array) Arguments array.<br />
54+
<strong>$flag</strong> (string) Flag to get the value.<br />
55+
<strong>$default</strong> (mixed) Default value for the flag. Default: NULL<br />
56+
57+
<p><strong>@return</strong> mixed </p>
58+
</div>
59+
60+
***
3361

34-
### get_temp_dir
3562

3663
```WP_CLI\Utils\get_temp_dir()```
3764

3865
Get the temp directory, and let the user know if it isn't writable.
3966

67+
<div>
68+
69+
<p><strong>@return</strong> string </p>
70+
</div>
71+
72+
***
73+
74+
## WP_CLI
75+
76+
77+
```WP_CLI::line( $message = null )```
78+
79+
Display a message in the CLI and end with a newline.
80+
Ignores --quiet flag. To respect, use WP_CLI::log()
81+
82+
<div>
83+
<strong>$message</strong> (string) <br />
84+
85+
</div>
86+
87+
***
88+
89+
90+
```WP_CLI::log( $message )```
91+
92+
Log an informational message.
93+
94+
<div>
95+
<strong>$message</strong> (string) <br />
96+
97+
</div>
98+
99+
***
100+
101+
102+
```WP_CLI::success( $message )```
103+
104+
Display a success in the CLI and end with a newline.
105+
106+
<div>
107+
<strong>$message</strong> (string) <br />
108+
109+
</div>
110+
111+
***
112+
113+
114+
```WP_CLI::debug( $message )```
115+
116+
Log information when --debug flag is used.
117+
Helpful for optionally showing greater detail when needed.
118+
119+
<div>
120+
<strong>$message</strong> (string) <br />
121+
122+
</div>
123+
124+
***
125+
126+
127+
```WP_CLI::warning( $message )```
128+
129+
Display a warning in the CLI and end with a newline.
130+
131+
<div>
132+
<strong>$message</strong> (string) <br />
133+
134+
</div>
135+
136+
***
137+
138+
139+
```WP_CLI::error( $message, $exit = true )```
140+
141+
Display an error in the CLI and end with a newline.
142+
143+
<div>
144+
<strong>$message</strong> (string|WP_Error) <br />
145+
<strong>$exit</strong> (bool) if true, the script will exit()<br />
146+
147+
</div>
148+
149+
***
150+
151+
152+
```WP_CLI::error_multi_line( $message_lines )```
153+
154+
Display an error in the CLI and end with a newline.
155+
156+
<div>
157+
<strong>$message</strong> (array) each element from the array will be printed on its own line<br />
158+
159+
</div>
160+
161+
***
162+

‎_templates/api-list.mustache‎

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,19 @@
11
{{#apis}}
22

3-
### {{short_name}}
4-
53
```{{signature}}```
64

75
{{phpdoc.description}}
86

7+
<div>
8+
{{#phpdoc.parameters.param}}
9+
<strong>{{1}}</strong> ({{0}}) {{2}}<br />
10+
{{/phpdoc.parameters.param}}
11+
12+
{{#phpdoc.parameters.return}}
13+
<p><strong>@return</strong> {{0}} {{2}}</p>
14+
{{/phpdoc.parameters.return}}
15+
</div>
16+
17+
***
18+
919
{{/apis}}

‎command.php‎

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,21 @@ function api_dump() {
2222
}
2323
$apis[] = get_simple_representation( $reflection );
2424
}
25+
$classes = get_declared_classes();
26+
foreach( $classes as $class ) {
27+
if ( false === stripos( $class, 'WP_CLI' ) ) {
28+
continue;
29+
}
30+
$reflection = new \ReflectionClass( $class );
31+
foreach( $reflection->getMethods() as $method ) {
32+
$method_reflection = new \ReflectionMethod( $method->class, $method->name );
33+
$phpdoc = $method_reflection->getDocComment();
34+
if ( false === stripos( $phpdoc, '@access public' ) ) {
35+
continue;
36+
}
37+
$apis[] = get_simple_representation( $method_reflection );
38+
}
39+
}
2540
echo json_encode( $apis );
2641
}
2742
\WP_CLI::add_command( 'cli api-dump', '\WP_CLI_Org\api_dump' );
@@ -65,12 +80,26 @@ function get_simple_representation( $reflection ) {
6580
$signature = $signature . '()';
6681
}
6782
$phpdoc = $reflection->getDocComment();
83+
$type = strtolower( str_replace( 'Reflection', '', get_class( $reflection ) ) );
84+
$class = '';
85+
switch ( $type ) {
86+
case 'function':
87+
$full_name = $reflection->getName();
88+
break;
89+
case 'method':
90+
$separator = $reflection->isStatic() ? '::' : '->';
91+
$class = $reflection->class;
92+
$full_name = $class . $separator . $reflection->getName();
93+
$signature = $class . $separator . $signature;
94+
break;
95+
}
6896
return array(
6997
'phpdoc' => parse_docblock( $phpdoc ),
70-
'type' => is_a( $reflection, 'ReflectionFunction' ) ? 'function' : 'method',
98+
'type' => $type,
7199
'signature' => $signature,
72100
'short_name' => $reflection->getShortName(),
73-
'full_name' => $reflection->getName(),
101+
'full_name' => $full_name,
102+
'class' => $class,
74103
);
75104
}
76105

0 commit comments

Comments
 (0)