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

[Dave Hall]

Ralf Becker <address@hidden> wrote:

> My thoughts about docs:
> 
> 1) I vote for inline-docs for documenting the functions and 
> arguments. 
> In my opinion everything else will never be very up-to-date. I 
> completly 
> disagree with probiz that nothing is documented in the API. I 
> personly 
> document everything, which is not, when I touch that class or 
> function. 
> Still the points of the discussion are very small, as the 
> differences in 
> our existing inline-doc-standard and the php-doc standard. With a 
> view 
> lines of customisation (far less lines as the disscussion alread 
> took 
> ;-) ) the existing parsers could be modified to read both.

I understand the need for basic inline docs.  I also find the php.net
manual very easy.  I have a simple bookmark in moz which allows me to
type php function and bingo i have the page i need - with see also for
other things which might help.  If using inline docs, sometimes I find
myself checking 3 or 4 files (my memory is not the bext at times).

> 
> 2) General concepts should be documented in a different way! I 
> would 
> prefer a wiki over docbook/html as it allows more developers a 
> simultanious access. The Inline docs should be able to be linked 
> in at 
> runtime. Provide macros for our wiki to do so is, beside 
> better/more 
> granularity in the access-control, the highest priority on my todo-
> list 
> for the wiki.

This does sound like a good idea.  I really should finish the anon user
support in knowledgebase/phpbrain which supports user comments also.

> 
> 3) More people should have write-rights to the wiki as it is the 
> case at 
> the moment. We might only want to look a view top-level pages so 
> only 
> some people can link in docs on that level.

I am all for increasing access to the wiki, once we have better acls.

> 
> Ralf
> -- 
> -------------------------------------------------------------------
> ---
> Ralf Becker
> OUTDOOR UNLIMITED Training GmbH                Telefon 0631 / 
> 31657-0
> Leibnizstraße 17                               Telefax 0631 / 
> 31657-26
> D-67663 Kaiserslautern            EMail address@hidden
> 
> 
> 
> _______________________________________________
> Phpgroupware-developers mailing list
> address@hidden
> http://mail.gnu.org/mailman/listinfo/phpgroupware-developers
> 
>

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