@@ -272,44 +272,23 @@ use these rules.
2722721. 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 * /
285285PHP_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
315294To 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
334313aliases listed in the documentation for the parent function. For ease of
335314reference, user-functions with completely different names, that alias to the
336315same 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
340318Backwards compatible functions and names should be maintained as long as the
341319code can be reasonably be kept as part of the codebase. See the `README` in the
0 commit comments