[PHP-DOC] cvs: phpdoc / README From: Ron Chmara (ron <email protected>)
Date: 10/17/00

ronabop Tue Oct 17 20:07:30 2000 EDT

  Modified files:
    /phpdoc README
  Log:
  Updated for function naming rules discussed 9/12.Anybody know a good reason why the skeletons lack closing tags?
  
Index: phpdoc/README
diff -u phpdoc/README:1.6 phpdoc/README:1.7
--- phpdoc/README:1.6 Sun Aug 6 08:33:07 2000
+++ phpdoc/README Tue Oct 17 20:07:30 2000
@@ -53,6 +53,60 @@
     6. The <refsect1><title> tag was set incorrectly when
        converting from sgml-tools. For normal function reference, the
        text "Description" should be used instead of the function name.
+
+WHAT TO DOCUMENT
+
+ 1. Only major functions should be documented, functions which are
+ typographic variants may be mentioned, but should not be
+ documented as separate functions. They instead should be
+ referenced in the parent function as an alias. Functions which
+ have completely different names, however, should be documented as
+ separate entries, for ease of reference.
+
+ Examples:
+ mysql_db_name and mysql_dbname will be documented as the same
+ function, with the latter being listed as an alias of the
+ former.
+
+ show_source and highlight_file will be documented as two
+ different functions (one as an alias), as the names are
+ completely different, and one name is not likely to be found
+ if looking for the name of the other.
+
+ 2. Function names should be created, and documented, in lower-case
+ format with an underscore separating the name components. If
+ there are several variants, use the one with the least amount
+ of components.
+
+ Good:
+ 'mcrypt_enc_self_test'
+ 'mysql_list_fields'
+
+ Ok:
+ 'mcrypt_module_get_algo_supported_key_sizes'
+ (could be 'mcrypt_mod_get_algo_sup_key_sizes'?)
+ 'get_html_translation_table'
+ (could be 'html_get_trans_table'?)
+
+ Bad:
+ 'hw_GetObjectByQueryCollObj'
+ 'pg_setclientencoding'
+
+ 3. Functions which are kept only for backwards compatibility should
+ be listed under their current parent names, and not documented as
+ separate functions. Backwards compatible functions and
+ documentation for them should be maintained as long as the code
+ can be reasonably kept as part of the PHP codebase.
+
+ 4. Short code examples are much more desirable than long ones.
+ If a function is extremely complex, a suitable place to put
+ a longer example is in the chapter introduction.
+
+ 5. Brevity is appreciated. Long winded descriptions of each and
+ every function are not appropriate for the reference sections.
+ Using the errata comments as guidelines, it's easier to tell when
+ more documentation is needed, as well as the inverse, when too
+ much documentation in one section has increased confusion.
     
 SKELETONS