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

[Jason Wies]

On Sat, Jun 28, 2003 at 08:50:45AM -0700, Dan Kuykendall wrote:
> Here are the reasons I have for moving away from inline-docs, to a 
> seperate external solution.
> 
> 1) Having multi versions of the same class, such as with our db classes, 
> causes duplication in documentation effort and a bunch of unneeded 
> resulting documentation. We should only document the db class once, and 
> users will know it will always work the same no matter which database 
> they are using.

That's why it would be better to put the function prototypes in the shared
class and document them there.  There is no reason to have documentation in
the backend classes (sql, ldap) at all, since they shouldn't have any public
functions that aren't part of the API definition.  The same goes for public
class variables (if any), which shouldn't even be declared in the backend
class because they are identical across all the backend classes.

As for inline vs. outside, I don't think it really matters to new developers
where the documentation is.  But I don't think that the API developers have
the resolve to break out lyx every time they make a change.  And the chances
are low of finding a documentation writer willing to keep up with all the
changes in the API and understand and document them.

Jason