Skip to content

Commit 4757998

Browse files
MaxSemkocsismate
authored andcommitted
Remove requirements for proto comments from CODING_STANDARDS
They've been made obsolete by .stub.php files and are often outdated as they're not the source of truth.
1 parent 0280b83 commit 4757998

File tree

1 file changed

+8
-30
lines changed

1 file changed

+8
-30
lines changed

CODING_STANDARDS.md

+8-30
Original file line numberDiff line numberDiff line change
@@ -272,44 +272,23 @@ use these rules.
272272
1. Extensions should be well tested using `*.phpt` tests. Read about that at
273273
[qa.php.net](https://qa.php.net/write-test.php) documentation.
274274

275-
## Documentation and folding hooks
275+
## Folding hooks
276276

277-
In order to make sure that the online documentation stays in line with the code,
278-
each user-level function should have its user-level function prototype before it
279-
along with a brief one-line description of what the function does. It would look
280-
like this:
277+
Use `{{{` symbols for the folding mode in Emacs and vim (`set fdm=marker`).
278+
Folding is very useful when dealing with large files because you can scroll
279+
through the file quickly and just unfold the function you wish to work on.
280+
The `}}}` at the end of each function marks the end of the fold, and should
281+
be on a separate line.
281282

282283
```c
283-
/* {{{ proto int abs(int number)
284-
Returns the absolute value of the number */
284+
/* {{{ Returns the absolute value of the number */
285285
PHP_FUNCTION(abs)
286286
{
287287
...
288288
}
289289
/* }}} */
290290
```
291291

292-
The `{{{` symbols are the default folding symbols for the folding mode in Emacs
293-
and vim (`set fdm=marker`). Folding is very useful when dealing with large files
294-
because you can scroll through the file quickly and just unfold the function you
295-
wish to work on. The `}}}` at the end of each function marks the end of the
296-
fold, and should be on a separate line.
297-
298-
The `proto` keyword there is just a helper for the `doc/genfuncsummary` script
299-
which generates a full function summary. Having this keyword in front of the
300-
function prototypes allows us to put folds elsewhere in the code without
301-
messing up the function summary.
302-
303-
Optional arguments are written like this:
304-
305-
```c
306-
/* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]])
307-
Returns a header object with the defined parameters */
308-
```
309-
310-
And yes, please keep the prototype on a single line, even if that line is
311-
massive.
312-
313292
## New and experimental functions
314293

315294
To reduce the problems normally associated with the first public implementation
@@ -334,8 +313,7 @@ purposes, these will only be documented by the most current name, with the
334313
aliases listed in the documentation for the parent function. For ease of
335314
reference, user-functions with completely different names, that alias to the
336315
same function (such as `highlight_file` and `show_source`), will be separately
337-
documented. The proto should still be included, describing which function is
338-
aliased.
316+
documented.
339317

340318
Backwards compatible functions and names should be maintained as long as the
341319
code can be reasonably be kept as part of the codebase. See the `README` in the

0 commit comments

Comments
 (0)