Re: Software documentation...

Randy Howard wrote:
Chuck F. wrote:
Randy Howard wrote: 
jacob navia wrote:

NO, it is necessary to know what that dammed function DOES
and that will never be written by doxygen or similar
tools.


All of this thread is OT here, but from the above it appears
you haven't spent very long (if any) with doxygen.  It *can*
be used to generate useful documentation.  To do so, you
simply add comments formatted correctly for its consumption,
and out comes what amounts to detailed man pages.


As far as I am concerned things like doxygen are simply a
means of maintaining documentation in the same source file as
the code.

Correct. It is easier to keep the docs in sync with the code when they are side by side, but still not foolproof.

This can negatively affect the understandability of the docs,
especially if the actual code is poorly structured.


Even in 2006, there is still no cure for poorly structured code.
Oh well...

There is no magic involved.

Was magic implied?

I think some people are expecting to take their source file, as it stands, feed it into doxygen or the like, and receive an impressive and accurate documentation file. That may require several wands.

--
"If you want to post a followup via groups.google.com, don't use
 the broken "Reply" link at the bottom of the article.  Click on
 "show options" at the top of the article, then click on the
 "Reply" at the bottom of the article headers." - Keith Thompson
More details at: <http://cfaj.freeshell.org/google/>
.

Relevant Pages

  • Re: PHP Career Advice
    ... You may be able to build it in a weekend, but what about all the documentation for the NEXT guy who has to modify it, and the user documentation, and the training course and manual you have to write. ... The last $500k job I did..probably the last in my professional career - I spent about 4 days installing and setting up kit onsite, I spent 6 days configuring at base, I spent 2 weeks writing the spec, and another 5 days writing training courses and 14 days delivering them. ... Secondly you area systems analyst, and finally your are an ANAL PROG them coding to a spec, and after that the dreaded TECH AUTH and CODE TESTER who rip the thing to pieces and find all its problems and document the thing in PLAIN ENGLISH for the people who think computers are spawn of the devil.. ...
    (comp.lang.php)
  • Re: Embedded programming usually solo?
    ... > indeed a great concern with the bottom line. ... Creating good documentation usually has a beneficial effect on the ... > don't pay NASA rates and we're still in profit. ... I also tend to comment in the source code headers to indicate the intent ...
    (comp.arch.embedded)
  • Re: Toward a Forth thats easier to learn
    ... You are right, the classes I teach are necessarily bottom up, as the students are either working with an application written by others in their organization or haven't been written yet at all. ... But for the general problem of initiating new would-be Forth users, for applications yet to be written, a bottom-up course also works great. ... Their program was written in a modified LMI Forth with virtually no documentation or comments, and a lot of the old code was really bad. ... This is very common in applications written by problem domain experts, and your solution is the correct one. ...
    (comp.lang.forth)
  • Re: SBS 2008 Swing Migration
    ... 'I wound up building the temporary DC about eight times and spent three straight weekends on it.' ... A basic premise Jeff worked from when developing the original SwingIT process was 'business continuance' and the ability to 'back out' of the process and start again, ... documentation and shot myself in the foot. ...
    (microsoft.public.windows.server.sbs)
  • Re: Datacolumn Value changing method
    ... calculated column that derives its value from ... Down near the bottom of the ... documentation page, it describes an IIF function, that you might be ... Prev by Date: ...
    (microsoft.public.dotnet.csharp.general)