[wp-hackers] Inline documentation
carthik at gmail.com
Thu Feb 16 15:15:53 GMT 2006
On 2/16/06, Mark Jaquith <mark.wordpress at txfx.net> wrote:
> 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.
This is why I suggested working on a seperate copy of the core code
and then the decision to merge changes into the core can be made at a
later dat, when the contributions are sufficiently mature and
verified. People can still use the concurrent documentation repo's
sources for development/information in the meantime - nothing to stop
them from doing that.
> Mark Jaquith
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
University of Central Florida
More information about the wp-hackers