[wp-hackers] Proposal for a function commenting convention

[Peter Westwood]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Jacob wrote:
> 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: [1],[2],[3] and adding documentation
where provided [4]

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
specifies:

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
we go.
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!

[1] http://trac.wordpress.org/changeset/6198
[2] http://trac.wordpress.org/changeset/6199
[3] http://trac.wordpress.org/changeset/6228
[4] http://trac.wordpress.org/changeset/6200

westi
- --
Peter Westwood
http://blog.ftwr.co.uk
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFHEfc7VPRdzag0AcURAkNPAKC094f3EpNSd+3zRko37eU04/VWsACfUORh
3Z6piBsEwJ55H5YupJPzp6g=
=Mu0l
-----END PGP SIGNATURE-----