@@ -272,44 +272,23 @@ use these rules.
272
272
1. Extensions should be well tested using `*.phpt` tests. Read about that at
273
273
[qa.php.net](https: //qa.php.net /write-test.php) documentation.
274
274
275
- ## Documentation and folding hooks
275
+ ## Folding hooks
276
276
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.
281
282
282
283
```c
283
- /* {{{ proto int abs(int number)
284
- Returns the absolute value of the number * /
284
+ /* {{{ Returns the absolute value of the number * /
285
285
PHP_FUNCTION(abs)
286
286
{
287
287
...
288
288
}
289
289
/* }}} * /
290
290
```
291
291
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
-
313
292
## New and experimental functions
314
293
315
294
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
334
313
aliases listed in the documentation for the parent function. For ease of
335
314
reference, user-functions with completely different names, that alias to the
336
315
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.
339
317
340
318
Backwards compatible functions and names should be maintained as long as the
341
319
code can be reasonably be kept as part of the codebase. See the `README` in the
0 commit comments