[wp-hackers] Proposal for a function commenting convention

[Jacob]

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.

I've given up with that crap, getting my ass jumped for having the 
audacity to suggest using a better framework pretty much left me 
drained. Documentation is fun, discussing life changing paradigm 
switches is not.

*Rest below: *

Travis Snoozy wrote:
> 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).
>   
I thought similar, but I figured that plugin authors might be concerned 
about when the function was added as opposed to when it will be 
released. As I agree with you, I'm going to do this instead. Unless 
someone has a more compelling argument on why #1 would be useful given 
the plugin developer position.
>   
>> 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).
>   
I disagree with that on the basis that current development doesn't care 
about what the function should do, that is lost with the developer that 
wrote it. It can only be assumed that something is broken and then a 
trac report can be created or postulate what it should do, which I 
believe that they call such reports "enhancements."

I had similar problems documenting the taxonomy API and I tried very 
hard to be neutral. For every "WTF?" I had, there was probably an 
explanation or purpose I was missing. Of course, someone had a similar 
"WTF?" and spoke up, upon which said WTF was corrected.

Spending too much time contemplating whether something is broken based 
on code review is time wasted in my opinion. Documentation should be 
written about what the code *does* not what it should do. If such a case 
is found, then the documentation should point out workarounds, until 
such fixes are committed.

Dev review would be nice, but if the taxonomy documentation is any 
indication, those are non-existent. I would have very much liked to of 
had the developer go over and reply back, either "that documentation is 
wrong or incomplete for such-and-such function" or "Yeah, that is right 
and what I had in mind." Oh well, when all you have to go by is what you 
read and can see, it causes even more strain trying to figure out 
whether or not the developer intended the WTF and really for that, you 
need unit tests to back up the assertion and not opinion from reading 
the code alone.

No dev review should be expected or needed, let the code speak for 
itself. Just assert the documentation to be true based on the code, and 
until another speaks up and states otherwise.

>   
>> 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.).
>   

I may be misunderstanding you, but I think that perhaps some of that 
information belongs to the class in question or in the long description 
and not in the return description. From what I understand, the @return 
and @param are supposed to be very short descriptions on what to expect. 
I would assume any further information would be in @example and @tutorial.

>   
>> 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.
>   

I did not concern myself with the documentation I wrote above. All 
globals and defines need to be considered public by the very nature of 
both. I do agree with documentation priority. However, in the community 
context, such a thing does not exist without a committee and in open 
source, there is no committee.

>   
>> 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.
>   

I was unclear, I meant should we rather assume that what we the phpdoc 
author believe to be private get full documentation, short and long, or 
try to only do short or only move the short comments, only if they exist 
previously to phpdoc format?

I did not waste my time writing long documentation for 
wp_unregister_GLOBALS(), because I would assume that the core devs know 
what it does, since I know what it does. No one else needs to care about 
what it does, only if it works and that isn't the documentation writers 
job, it is for unit tests to figure.
>   
>> 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).
My reasoning was that just because a function isn't documented doesn't 
mean it ceases to exist. Much like the WP hooks documentation site [1] I 
believe that any phpDocumentator site should have the full list of 
WordPress functions, even if they aren't fully documented.

The rest, I would need clarification on as I probably move on a 
completely different direction than what you were trying to explain.

Jacob Santos

[1] http://wphooks.flatearth.org/