[wp-hackers] Inline documentation

[Carthik Sharma]

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.

Carthik.
> --
> Mark Jaquith
> http://txfx.net/
>
>
> _______________________________________________
> wp-hackers mailing list
> wp-hackers at lists.automattic.com
> http://lists.automattic.com/mailman/listinfo/wp-hackers
>


--
Ph.D. Candidate
University of Central Florida
Homepage: http://carthik.net