[wp-hackers] Proposal for a function commenting convention

[Travis Snoozy]

On Sun, 14 Oct 2007 03:59:15 -0500, Jacob <wordpress at santosj.name>
wrote:

My opinions do not necessarily reflect those of the devs or the
community at large... ;)

The goal that I'm going for in all of this is to stop the bleeding --
the API is a (somewhat subtle) mess stability-wise, and documentation
is a requirement (and a big step forward) to fixing that. Ideally,
thinks would be "spec first, code second," but pragmatically speaking,
a "code, iterate, freeze" can be made to work similarly.

> In a nutshell:
> 
> 1. Should be include the "-bleeding", "-beta#", "-rc#" along with the 
> version if applicable. I vote yes.

My inclination would be not to -- I see no compelling reason to add this
level of granularity, as people target "WordPress 2.2.2+" or
"WordPress 2.3", not "WordPress 2.3 RC1".

Also, for maximum usefulness, it may be necessary to document the
major/breaking changes between the same function in different versions
of WordPress (e.g., get_the_title returning raw titles before 2.3, and
filtered titles with 2.3+). Trying to do this with bleeding, betas and
RCs would be a lot of work, with very little usefulness (again, because
people tend to target full releases; everything else is assumed
broken or in flux).

> 2. Do we concern ourselves with just wp-includes/*.php or with the 
> entire function codebase, except for admin (unless you really want
> to).

You're putting the cart ahead of the horse. All public APIs should
probably be a subset of wp-includes/* (not that they are), but it's not
necessarily true that everything in wp-includes/* is a public API.
Determining which are public and which are not should probably come
first. Then, the public APIs should get priority on documentation.
There's an added twist in that public APIs need to be documented based
on what they *should* do, as opposed to what they currently do -- this
will require inputs from the devs (at least), and some level of
consensus. If the implementation is broken vs. what it should do, then
multiple documentation may be required (as noted in #1).

> 3. What do we do with functions that we apply @since, @return,
> and @param too?

A style guide would be a Good Thing to ensure that the entries are
consistent, as well as to help ensure that all the information is
included for each function (e.g., when returning non-class objects,
which properties the objects have, what their value types are, etc.).

> 4. Since we are documenting functions, should we also document files 
> (file level phpDoc), globals, and defines (thinking more of the wider 
> context of having a phpdocumentor site).

Same deal here as with the functions -- the globals/defines that are
considered public need to be sorted from the ones that are private, and
the public ones given documentation priority.

> 5. Should we hold all functions in public namespace? I'm limiting
> some such as wp_unregister_GLOBALS() and setting it to private,
> meaning it shouldn't show up on any phpdocumentor site. Do we really
> need to fully document those functions, because no one should be
> using it. If it doesn't work, then it really needs to be unit tested
> to see if it is broken.

Pretty much the same issue as with #2 and #4. There is no crystal-clear
delineation between internal/private and external at the moment.

> For #3:
> 
> I was thinking of boilerplate text:
> 
> /**
>  * function_name() - Undocumented
>  *
>  * Undocumented
>  *
>  * @package Whatever
>  * @subpackage WhateverSub
>  * @since 1.5
>  * @param if applicable
>  * @return null Does not return anything or returns no explicit type.
>  */
> 
> The "Undocumented" text would serve as a starting point for future 
> documentation of procedural code. That is, it would give the reader a 
> placeholder to document the function and submit the patch to trac. I 
> think the simple functions are too easy to not fully document.

For new functions, the boilerplate should probably be marked "private"
at first, and only get a version (and be switched to public) after
thorough review to make sure that the API isn't horribly broken in some
way. For existing functions, the boilerplate should probably still be
marked private until the API is sanity-checked, documented and frozen,
and the version should be set to either the current version (if it
conforms to the spec) or the next version (if the current version
doesn't conform). In either case, there should be a note to back-trace
and update, indicating how far back checks have been made.

I'm also partial to precondition/postcondition sections, as a standard
way to document the value limitations on input params (at minimum).


-- 
Travis 

In Series maintainer
Random coder & quality guy
<http://remstate.com/>