[PythonCAD] Doc tools are not the solution.

[Glenn Meader]

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?id=program_code_description

Feel free to add your contributions to the PythonCAD Wiki!

Glenn Meader
Berkeley, CA

-----Original Message-----
From: pythoncad-bounces at python.org [mailto:pythoncad-bounces at python.org] On
Behalf Of nescivi
Sent: Friday, May 25, 2007 6:07 PM
To: pythoncad at python.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