PHP Documentation - a few coding standards

Author

a few coding standards

Philip Olson

2004-07-28, 3:57 pm

Hello all!

Just want to confirm that the following are true as I don't
believe these have been made official [yet]:

a) No ending period in the reftitle
b) No ending period in the see also
c) Only part of docs wider than 78 characters is
methodsynopsis
d) New examples use ' not " wherever possible (this is
old since PEAR coding standards describe it but few
do it, not sure why)
e) All new (and eventually old) docs will use the new
upcoming 'refsect style'

Regarding (a), it's a little strange when a reftitle has
multiple sentences, or commas, as it means only partial
punctuation is used when we leave off the ending period.
Should we live with that? Most are not this way so it
should be fine. Also, many times these titles aren't
even complete sentences.

With (b) it would be nice if we didn't manually type in
commas either but it seems we abandoned that idea. Goba?
Adding them feels a little dirty but also simple and
doable.

As far as (e) goes I'll write a separate email regarding
a CHANGELOG refsect1 proposal (this has been discussed
many times!) but other than that what do you guys think?

Regards,
Philip

Aidan Lister

2004-07-28, 3:57 pm

Hi Philip,

I'm new, so this has probably been discussed a million times.

Do we have to leave all the crap at the bottom of every file? How many
people use vim?
Is there a better way to do it?

A pretty rough estimate, but I'd say those comments account for atleast
1/3rd of the size of the xml sources?

"Philip Olson" <philip@cornado.com> wrote in message
news:Pine.BSF.4.10.10407271329320.48202-100000@merlin.pegasi.net...
> Hello all!
>
> Just want to confirm that the following are true as I don't
> believe these have been made official [yet]:
>
> a) No ending period in the reftitle
> b) No ending period in the see also
> c) Only part of docs wider than 78 characters is
> methodsynopsis
> d) New examples use ' not " wherever possible (this is
> old since PEAR coding standards describe it but few
> do it, not sure why)
> e) All new (and eventually old) docs will use the new
> upcoming 'refsect style'
>
> Regarding (a), it's a little strange when a reftitle has
> multiple sentences, or commas, as it means only partial
> punctuation is used when we leave off the ending period.
> Should we live with that? Most are not this way so it
> should be fine. Also, many times these titles aren't
> even complete sentences.
>
> With (b) it would be nice if we didn't manually type in
> commas either but it seems we abandoned that idea. Goba?
> Adding them feels a little dirty but also simple and
> doable.
>
> As far as (e) goes I'll write a separate email regarding
> a CHANGELOG refsect1 proposal (this has been discussed
> many times!) but other than that what do you guys think?
>
> Regards,
> Philip

Sponsored Links