Re: Doc tools are not the solution.

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.

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.
This requires a human to actually write descriptions of the
architecture --
how the flow of control moves between objects. How the
objects actually
interact when a user clicks on some UI widget. Prose
examples that
demonstrate how each major feature works... Perhaps even
flowcharts...

José gives an excellent suggestion below.

Art, in what city do you live?  Perhaps someone could visit
you and record
an audio interview as you describe the architecture...

I started documenting the code on the PythonCAD Wiki:
http://morgul.no-ip.com/dokuwiki/doku.php?i
d=program_code_description

Feel free to add your contributions to the PythonCAD Wiki!

Glenn Meader
Berkeley, CA

-----Original Message-----
From: pythoncad-bouncespython.org [mailto:pythoncad-bouncespython.org] On
Behalf Of nescivi
Sent: Friday, May 25, 2007 6:07 PM
To: pythoncadpython.org
Subject: Re: [PythonCAD] Centralized SCM not the problem

On Friday 25 May 2007 10:00:47 Eric Wilhelm wrote:
> # from José Antonio Martín Prieto
>
> # on Thursday 24 May 2007 11:39 pm:
> >So I have a suggestion. In order to help casual
developers, maybe Art
> >(and other expert developers, if any) could write a
more exhaustive
> >guide for PythonCAD coding, so that the
architecture is more
> >understandable.
>
> Has there been any work in the python community to
create dot (graphviz)
> diagrams of code flow/linkage?  Yes that could be
difficult to do as
> static analysis, but maybe possible at runtime.

does Doxygen work on Python code?

that is usually quite a good method to get to know your way
around code.

sincerely,
marije


_______________________________________________
PythonCAD mailing list
PythonCADpython.org
htt
p://mail.python.org/mailman/listinfo/pythoncad

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
_______________________________________________
PythonCAD mailing list
PythonCADpython.org
htt
p://mail.python.org/mailman/listinfo/pythoncad