[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...
Regards
Floris
--
Debian GNU/Linux -- The Power of Freedom
www.debian.org | www.gnu.org | www.kernel.org
More information about the PythonCAD
mailing list