[PythonCAD] Doc tools are not the solution.

Floris Bruynooghe floris.bruynooghe at gmail.com
Sat May 26 14:12:25 CEST 2007

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


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

More information about the PythonCAD mailing list