CVS update: php3

Date: Friday November 6, 1998 @ 16:11 Author: rasmus Update of /repository/php3 In directory asf:/u2/tmp/cvs-serv9358 Modified Files: CODING_STANDARDS Log Message: Add prototype documentation blurb to CODING_STANDARDS Index: php3/CODING_STANDARDS diff -c php3/CODING_STANDARDS:1.7 php3/CODING_STANDARDS:1.8 *** php3/CODING_STANDARDS:1.7 Fri Sep 11 16:21:50 1998 --- php3/CODING_STANDARDS Fri Nov 6 16:11:01 1998 *************** *** 113,115 **** --- 113,147 ---- groups in a block. Maintain at least one empty line between two functions, preferably two. + Documentation and Folding Hooks + ------------------------------- + + In order to make sure that the online documentation stays in line with + the code, each user-level function should have its user-level function + prototype before it along with a brief one-line description of what the + function does. It would look like this: + + /* {{{ proto int abs(int number) + Return the absolute value of the number */ + void php3_abs(INTERNAL_FUNCTION_PARAMETERS) { + ... + } /* }}} */ + + The {{{ symbols are the default folding symbols for the folding mode in + Emacs. vim will soon have support for folding as well. Folding is very + useful when dealing with large files because you can scroll through the + file quickly and just unfold the function you wish to work on. The }}} + at the end of each function marks the end of the fold. + + The "proto" keyword there is just a helper for the doc/genfuncsummary script + which generates a full function summary. Having this keyword in front of the + function prototypes allows us to put folds elsewhere in the code without + messing up the function summary. + + Optional arguments are written like this: + + /* {{{ proto object imap_header(int stream_id, int msg_no [, int from_length [, int subject_length [, string default_host]]]) + + And yes, please keep everything on a single line, even if that line is massive. + + -- PHP Development Mailing List http://www.php.net/ To unsubscribe send an empty message to php-dev-unsubscribe@lists.php.net For help: php-dev-help@lists.php.net