Re: Reimplementing code, was: gEDA-user: Free Dog meeting report: Notes on the topics we discussed

[Richard Urwin <richard@xxxxxxxxxxxxxxx>]

On Tuesday 20 Sep 2005 18:40, Stuart Brorson wrote:
> One thing we do need, however, is more transparency into how the code
> works.  Personally, I have posted a .pdf drawing of (some of) the
> data structures used by libgeda & how they work at my website here:
>
> http://www.brorson.com/gEDA/gEDA_Structures_20050108.pdf
>
> My little utility, gattrib, which is part of gEDA/gaf includes a
> bunch of (hopefully) high-level documentation in its source tree. 
> Finally, I have also started (but not finished or distributed) an OOO
> doc describing the calling args and returns from many (and someday
> all) of the fcns in libgeda.
>
> My point is this:  If there are others out there who share my view,
> I'd be happy to post my libgeda doc and let others investigate the
> libgeda, gschem, gnetlist, etc. code and add to the doc.  I think it
> would help enlarge the developement community if we had a better set
> of docs describing how the code works.
>
> In the end, I think more transparency into the existing code base
> would be much more useful than writing or re-writing anything in the
> latest hype-language.
>
> Let me know if you want to share the work of documenting libgeda!

The trouble with a stand-alone document is it is correct only until the 
next developer makes a change. You will spend the rest of your life 
berating developers for not updating the docs.

Have you considered "doxygen" (see sourceforge). It gives you just about 
everything you mention above except the data structures (and does some 
of that for C++ classes,) including dependency graphs.

BTW:  example of a good Java app with complex gui and wide 
multi-platform support: jEdit. (also on sourceforge)  (No axe to grind; 
I'm just saying. I agree a huge code-base can't reasonably be rewritten 
- and I wouldn't choose Java even if I had to do such a thing.)

-- 
Richard Urwin