Re: RE: [Phpgroupware-developers] Standard source code header and php Documentor

[Dave Hall]

Kai Hofmann <address@hidden> wrote:

> Hi Dave,
> 
> > Firstly, we do not use phpdoc as our inline documentation.  
> > We use this
> > http://developer.apple.com/darwin/projects/headerdoc/
> 
> oh sorry I was not aware of this - because the source looks like 
> you are
> using nothing.

Really?  A lot of the classes are documented.  I know my apps need
documenting, which will be done when i have time to scratch my bum.

> 
> > This duplicates most of the information already in the 
> > standard header.
> 
> So maybe changing the standard header would be worth discussion?

The standard header was developed in consultation with some GNU people
and our active API contributors.

> 
> > The license link is incorrect it should be
> > http://www.gnu.org/licenses/gpl.html
> 
> Sorry to say but within the api headers there is mentioned the 
> lgpl - so I
> used this one
> because its already there.
> I license change have to be discussed and voted I think!

Ok then use http://www.gnu.org/licenses/lgpl.html ... my point was that
you should use the official version of the license.  Also not all of the
LGPL.  We already have the condensed licensing info in the standard header.

> 
> Copy from phpgwapi/inc/class.accounts_shared.inc.php

<snip />

> 
> maybe different parts of phpgw are under LGPL and others under GPL.
> 
> > Also the email address is perfect for spam harvesting.
> 
> It is also required for developer communication - its sometimes 
> really hard
> to found
> out your correct email addresses for personal question :(

Yes but using user at domain.com is pretty safe, better than user AT
domain DOT com or address@hidden


> 
> > If you really want to move to new documentation standard, then 
> propose> it to the project, not submit a patch - without 
> > consultataion.  
> 
> Oh sorry as said above the api code looks to me as there was no
> documentation standrad.
> So I would like to propose to use phpDocumentor as the standard.

Some justfications (or arguements for and against) for this would be nice.


> 
> > Also you
> > might want to outline what your plans are for moving to the new
> > standard, ie who is going to make the changes, what time lines, etc.
> 
> I plan (independend of probusiness!) to add phpDocumentor comments 
> to the
> complete phpgw API!
> Maybe someone out there who is interesting in helping me with this?
> 
> Because I only can do this in the evening or on weekends this will 
> take time
> until January 2004.

Wouldn't it be better to build on the work that has already been
started, rather than head off in another direction?  Especially with the
timelines you are talking about.  A lot of the api has apple docs, so
look at finishing that.

> 
> Also it would be helpful when I have contributor status to the api 
> for doing
> this.

API contributor status takes some time to obtain.  Post patches, which
is what most of our contributors must do for API changes - including our
translators.

Cheers

Dave

dave.hall.vcf
Description: Card for <dave.hall@mbox.com.au>