Scott Harrison wrote:
>
> Fine with me. Nice set of pages you have there. So I guess the next
> big
> question is,
>
> WHO WANTS TO HELP DOCUMENT THINGS?
>
> If volunteers send me ([EMAIL PROTECTED]) their e-mail addresses,
Well, I kinda already volunteered, so I'd like to contribute...
although for the next month or so my first priority will be what is
needed solely for my [payed] project.
> we can begin to set up a new effort at documentation. As soon (within
> a week) as there is some reasonable understanding as to how to proceed,
> we can begin communicating through dia-list as to what is going on.
However, please note that the purpose of my original question was to
locate
documentation & ideas that were already "there somewhere"... and to
avoid the
more tedious (and time-consuming) task of reverse-engineering.
(Yes, I know that we programmer's tend to be sloppy about documenting
for
others what we make... gotta have some trade secrets... ;-)
>
> Hubert Figuiere wrote:
[...snip...]
> >
> > Perhaps Doxygen (http://www.doxygen.org/) could be used as it allow to write
> > code and doc at the same time ?
That's an idea. But besides that, Doxygen might (?) have a problem
identifying
the classes buried in the Dia design, since after all it's C not C++ or
Java...
In my view, one of the problems with such automated tools to "resurrect
and/or
reverse engineer" existing code is that they're too accurate -- they
include
all the details and any patological interdependencies that might have
grown
into the source over the years, thereby obscuring the basic ideas &
structure.
(It cannot distinguish between important and unimportant design
features,
ending up showing just a lot of "noise".)
IMHO, merely converting code comments into HTML/RTF/whatever doesn't
improve
_that_ much over just reading the source files directly... It doesn't
always
reveal the structure.
But that's just me, though... :-)
Actually, I made a very tiny start using Dia itself (why not!?!!) and
the UML
elements, creating a class diagram based on header files and the README
file.
...until I found that this was very time-consuming since I had not
gained any
familiarity with the source beforehand.
-+-Ben-+-
