[wp-hackers] Proposal for a function commenting convention
peter.westwood at ftwr.co.uk
Sun Oct 14 11:02:19 GMT 2007
-----BEGIN PGP SIGNED MESSAGE-----
> Test DIFF here: http://www.santosj.name/wp-settings.phpdoc.diff -
> Comments, insults, suggestions welcome.
> Some of what you suggestion could only be approved by Matt, Mark, etc as
> it would be on them to enforce it. It would require they enforce it on
> themselves, I doubt such a suggestion would make it through. Seeing as
> the current style is (like it or not), code it and see if it breaks
> anything, I doubt the paradigm like "code, iterate, freeze, test,
> unfreeze, repeat" would work at this stage. Could send an email to Matt
> though, but still doubtful as it would require a whole new coding style
> and drastic change to development cycle.
Improving the documentation is welcome.
I have been trying to ensure that all new template tags/functions I add
are documented when they go in: ,, and adding documentation
where provided 
However, before we start on a mass documentation spree of the
undocumented code we really need to form a list of the tags we are going
to use from those available in phpDoc and valid values where appropriate.
It would be nice to see a proposal on the documentation format which
1. The set of @package tags we are going to use.
2. Whether or not we want to use @since and if so in how much detail do
3. How we handle deprecated functions.
If you have simple single function or file phpDoc patches that just add
documentation get them on trac and assigned to me and I will review and
check them in.
Better documentation will benefit everyone!
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
-----END PGP SIGNATURE-----
More information about the wp-hackers