[PythonCAD] Doc tools are not the solution.

[Floris Bruynooghe]

On Fri, May 25, 2007 at 07:41:49PM -0700, Glenn Meader wrote:
> Doxygen works with Python. It would be a somewhat useful to have Doxygen run
> on the PythonCAD code. Perhaps I will do that. I already tried PyDoc. It was
> not very useful.

I must agree here, I have before explored the code using pydoc trying
to learn my way around it.

> However using a doc tool is not a solution to the PythonCAD problem.
> 
> Doc tools are great for documenting APIs that were designed from the ground
> up to be a programmer *interface* to be used by others.
> 
> However, doc tools are not so good for documenting complete
> applications.

Sure, I partially agree here.  But I'll also argue that
PythonCAD/Generic *is* supposed to be an library with good API to be
used by the people hacking on the interfaces.

I have, a while ago, started to figure out to add complete docstrings
to something as basic as entity.py while reading the code.  I do
believe that a good structured program (which I'm sure pythoncad is)
and good docstrings (which it is lacking currently IMHO) help a great
deal with understanding it all.

That doesn't mean that the effort you describe, creating architecture
overviews, are not useful and important.  I just wanted to argue that
adding good docstings (and thus improving pydoc and doxygen) are also
a worthwile effort.  Maybe I should have a look at that again and
actually produce some patches...

Regards
Floris

-- 
Debian GNU/Linux -- The Power of Freedom
www.debian.org | www.gnu.org | www.kernel.org