[wp-hackers] Inline documentation

[Mark Jaquith]

On Feb 16, 2006, at 8:46 AM, Carthik Sharma wrote:

> Issues remaining are:
> 1) Writing a howto or a standards document describing followed norms
> and standards
> 2) Choosing the doc format/tool to use - phpDocumentor seems to be  
> the best bet
> 3) Creating an svn repo for this effort - Can Matt/WP.com help with
> hosting this?
> 4) Choosing a project lead/coordinator - Mark (txfx.net) - are you up
> for it? Other volunteers?

We still need word from Matt or Ryan that this is the sort of thing  
that they'd put into WP.  I think it sounds worthwhile, and I'd  
certainly like to help, but I don't have commit access, so it's not  
my call whether or not it goes in.

 From the Meetup logs from last night:

> [19:35] <SteamedPenguin> rboren: so something like var listing and  
> var typing would not go in?
[...]
> [19:36] <rboren> SteamedPenguin: I wouldn't right now, but we can  
> discuss on the hackers list and see where people fall.

So we still need to make a case for this.  If there are any silently  
agreeing lurkers, now is the time to voice your support.

Andy brought up an opposing argument (playing devil's advocate):

> [19:37] <skeltoac> The major argument I see opposed to extensive  
> commenting is that it takes time to review them.
> [19:38] <SteamedPenguin> skeltoac: a fair ammount of function  
> description can come straight out of the codex.
> [19:38] <SteamedPenguin> at least where template tags are concerned
> [19:40] <SteamedPenguin> skeltoac: since that stuff has the most  
> eyeballs it ought to be the first target for inline commenting as  
> well as the easiest to accomplish
> [19:40] <SteamedPenguin> making template tags a good test case, IMO

... and deconstructed it fairly well.

> [19:42] <skeltoac> You can always upload patches and ask for peer  
> review. If you have a good set of comments and they've been okayed  
> by a number of devs, Ryan doesn't have to spend his day reading  
> them over.

There are several people who, while they don't have commit access,  
get a certain amount of leeway when it comes to the patches they  
submit or recommend for commit.  I'd expect that these sorts of  
commits (that only consist of PHP comments) would get even more  
leeway, as they're not going to break anything.

We could work on patches amongst ourselves, and then when we think  
they're ready to go we could have 2 or 3 people sign off on it and  
send it off with a "commit" tag.

--
Mark Jaquith
http://txfx.net/