phpDocs for source code, consistent programming style [patch]

[GoogleCodeExporter]

Hi,

I was slightly frustrated how hard it's to find things in the source files, so 
I threw together documentation in form of a phpdoc following the direction set 
by the existing core additions. Yeah, I'm suggesting a patch that adds phpdocs 
and cleans up some stuff.

To this point I've documented all functions in txplib_db.php, txplib_forms.php 
and txplib_misc.php. You can see the generated docs from those files online 
here:
http://gocom.github.com/txp-api-doc/

Writing that has taken, well, let's say few days, and hopefully this (or some 
of it) could be merged to the project. A consistent documentation would be good 
and make others job a lot easier.

All added comments follow the exact same styling and rules, even grammatically:

* Uses @param, @see, @access, shortdesc, longdesc, @return and @deprecated 
where acceptable.
* Functions that are marked as deprecated reference replacement using @see.
* Functions that are plainly just for core purposes are marked to "private" 
using @access.
* Uses @package in effort to organize the large source files to manageable sets

In addition to documenting the code, I've updated the programming style to be 
more consistent. This includes proper default values ("hinting") and 
white-space:

* Closes all blocks consistently. For extendability and readability all 
statements use brakets.
* Every single bracket is on its own line.
* Uses consistent indentation, including sorts all instances of mixed spaces 
and tabs. Uses tabs for indentation, spaces within lines if needed.
* Fixes default argument values and sorts "hinting". 
* Hinting: Boolean arguments default to boolean instead of using "0" or "1". 
This is of course fully b/c. Makes things as "load_plugins()" much more clear.
* Hinting: Arguments that take constants and are optional, use a constant as 
the default value instead of the value of the constant.
* Arguments: Uses spaces after commas. E.g. $nospace,$messy='value',$foo 
becomes $nospace, $messy = 'value', $foo 

During sorting docs and styling, I've noticed few bugs which I've fixed:

* Fixed SQL escaping in get_author_name() and get_author_email(). The name was 
escaped twice.
* Fixed error handling in safe_field(). It didn't check if safe_query() 
returned results, but instead relied on error suppression.
* Fixed get_uploaded_file() to return FALSE also when move_uploaded_file() 
fails.
* Future compatibility: "DB" class to use PHP 5> style constructor.
* Some errors in the phpdocs.

I've also removed some duplicate code by aliasing/referencing. No compatibility 
changes, just creating wrappers:

* Uses doSpecial() in gTxt()
* Turns getCount() to wrapper of safe_count()
* Turns checkbox2() to wrapper of checkbox() w/ hard-coded value of "1"

The patch also includes few other miscellaneous changes:

* Casts safe_counts() results to a integer form a string. Preserves FALSE on an 
error.
* Replaced "\n" with "n" constant where acceptable.

Hopefully all this has some value to you guys and this can be integrated to the 
core so that we all can enjoy benefits that come with proper (-er) 
documentation.

Original issue reported on code.google.com by jukka.svahn@rahinaa.biz on 1 Oct 2012 at 8:35

Attachments:

• txplib_db.php.r4161.phpdoc.patch
• txplib_forms.php.r4161.phpdoc.patch
• txplib_misc.php.r4161.phpdoc.patch

[GoogleCodeExporter]

Attaching the real txplib_db.php patch file wouldn't hurt.

Original comment by jukka.svahn@rahinaa.biz on 1 Oct 2012 at 8:44

Attachments:

• txplib_db.php.r4161.phpdoc.patch

[GoogleCodeExporter]

Original comment by r.wetzlmayr on 4 Oct 2012 at 4:25

• Added labels: Milestone-4.6

[GoogleCodeExporter]

Please break these massive patches into manageable parts (docs changes, code 
formatting, functional changes). Downstream projects like e.g. MLP should be 
able to merge their relevant portions without combing through unrelated changes.

Original comment by r.wetzlmayr on 4 Oct 2012 at 7:25

• Changed state: Assigned

[GoogleCodeExporter]

Original comment by r.wetzlmayr on 11 Oct 2012 at 1:27