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

[Kai Hofmann]

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.org/api as written in nearly all phpgwapi
headers ???

> > > 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.

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

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.

> 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.

> > 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

> * Join the [mailing lists] - help out where you can

I am here ....

> * 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 concepts
have been posted

> * Write your mods/docs/translations and put it up somewhere for review
(and testing).

This has also been done as you know.


So whats the problem? Maybe your statement on wiki isn't complete?


Greetings

   Kai