[wp-hackers] Proposal for a function commenting convention

Peter Westwood peter.westwood at ftwr.co.uk
Sun Oct 14 11:02:19 GMT 2007

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

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

- --
Peter Westwood
Version: GnuPG v1.4.2 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org


More information about the wp-hackers mailing list