Re: 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.
> 
> I have seen the whole API while creating the ArgoUML diagram and 
> there was
> not really much documentation - also if it is there - why it is not
> available
> via the web under www.phpgroupware.orheaders ???

We have not had a doc maintainer for sometime now.  I want to overhaul
docs.phpgroupware.org to run off our wiki app, which should improve
this.  As for having the api documentation on the website, it won't fit
on one page!


> 
> > > > 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.
> 
> phpDocumentor has been developed especially for PHP code
> (based on javadoc) - so its advantage is keeping track of
> special PHP problems like different datatypes for one 
> variable/parameter.Also it directly parses the PHP code and 
> "understands it".
> Last but not least it creates an usable javadoc like output as I have
> proofen.

the apple docs support this too.

> 
> Also I have seen any generated apple headerdoc API documentation yet!

Have a look at doc/inlinedocparser.php

> 
> Last but not least using another free php project would be a better
> political choice
> and the documentation would be more similar to the pear one.
> 

I did not make the decision, all I am saying is why start changing it
when the job is not yet complete?  It would be less work to finish what
has been started, rather start over.


> > 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.
> 
> Sorry I don't see it in this way - so maybe someone other will do 
> that.

Then how do you see it?  cos you have lost me.  You are saying 6mths
work to start from scratch, so obviously it would be faster to build on
the existing base.

> > > 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.
> 
>
http://phpgroupware.org/devteam/wiki/index.php?page=Project+Contributor+Requ
> irements
> 
> > The process to being given developer status to the project is as 
> follows:>
> > * Submit a useful patch or 2 through [Savannah patch manager].
> >   o The patches could be code, docs, translations, templates 
> anything you
> think the project could benefi from
> >   o These patches should show your understanding of our code and
> development style.
> 
> This has been done - database documentation, API UML diagram as 
> well as a
> patch for phpDocumentor


I am yet to see this, several of you submissions have shown that this is
not the case.

> 
> > * Join the [mailing lists] - help out where you can
> 
> I am here ....

I have noticed

btw this is very selective quoting from that page!

> 
> > * Pick some part of the project that you feel you can make some real
> improvements on, find out who is in 
> >   charge of that part of the project and contact them. Submit your
> improvements to them and establish a 
> >   relationship with them. They will be the person who will let 
> us know if
> you should be added.
> 
> Thats the API as you should now - a lots of bug reports and design 
> conceptshave been posted

The API is a restricted component of the project.  See
http://mail.gnu.org/archive/html/phpgroupware-developers/2003-05/msg00169.html

> 
> > * Write your mods/docs/translations and put it up somewhere for 
> review(and testing).
> 
> This has also been done as you know.
> 

Well, the "bug reports" you have logged, not all are bug reports.  The
form they have taken has not been very useful.  For example ~10 reports
for different apps, with the same name is very annoying.  We currently
have ~160 open bugs, so clear descriptions make my (and others) life a
lot easier.

You have also failed to listen to feedback on the tracker.  Also code
changes which are not bugs are feature requests.  

> 
> So whats the problem? 

Shall I continue?

> Maybe your statement on wiki isn't complete?

Yes, I will add something about the API access being restricted.  This
is pretty well know but active participants in the project.

Cheers

Dave

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