Software documentation...

**Mike Wahler** · Jan 6 '06, 01:25 AM

Re: [OT] Software documentation.. .

"barcarolle r" <barcaroller@mu sic.net> wrote in message
news:Mfjvf.4110 0$X25.918782@ne ws20.bellglobal .com...[color=blue]
> I'm looking for a free software documentation tool that works equally well
> with C and C++. The ones I have found so far with Google are:
>
> - Doxygen
> - Robodoc
> - Natural Docs
>
> There probably are more. Does anyone have any recommendations regarding
> these[/color]

Try them out and determine if one or more of them fill your needs.
[color=blue]
> (and other) software documentation tools?[/color]

Visit www.google.com and search.

Rinse, repeat.

-Mike

**jacob navia** · Jan 6 '06, 07:25 AM

Re: Software documentation.. .

barcaroller a écrit :[color=blue]
> I'm looking for a free software documentation tool that works equally well
> with C and C++. The ones I have found so far with Google are:
>
> - Doxygen
> - Robodoc
> - Natural Docs
>
> There probably are more. Does anyone have any recommendations regarding
> these (and other) software documentation tools?
>
>
>[/color]
All those automatic documentation tools never replace
WRITING THE DOCS, even if they are in text format.

What bothers me is that people think they can save themselves
the work of writing the documentation by throwing a
few megabytes of automatically generated rubbish
at the unaware user, that thinks that there is
a documentation when in reality there is NONE.

NO, it is not enough to know that void fnx(int)
is defined in file fnx.c and it is used in
( stupid list of 20 files deleted)

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

The IDE of lcc-win32 had a module that wrote automatically
the documentation like doxygen. I eliminated it because of
this considerations: it would never say anything more than
what GREP would say anyway.

jacob

**Giannis Papadopoulos** · Jan 6 '06, 11:05 AM

Re: Software documentation.. .

jacob navia wrote:[color=blue]
> What bothers me is that people think they can save themselves
> the work of writing the documentation by throwing a
> few megabytes of automatically generated rubbish
> at the unaware user, that thinks that there is
> a documentation when in reality there is NONE.[/color]

However, when you create libraries, they are indeed really useful.

**Randy Howard** · Jan 6 '06, 02:05 PM

Re: Software documentation.. .

jacob navia wrote
(in article <43be190b$0$212 64$8fcfb975@new s.wanadoo.fr>):
[color=blue]
> NO, it is necessary to know what that dammed function DOES
> and that will never be written by doxygen or similar
> tools.[/color]

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.

--
Randy Howard (2reply remove FOOBAR)
"The power of accurate observation is called cynicism by those
who have not got it." - George Bernard Shaw
How 'bout them Horns?

**Chuck F.** · Jan 6 '06, 08:45 PM

Re: Software documentation.. .

Randy Howard wrote:[color=blue]
> jacob navia wrote:
>[color=green]
>> NO, it is necessary to know what that dammed function DOES and
>> that will never be written by doxygen or similar tools.[/color]
>
> 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.[/color]

As far as I am concerned things like doxygen are simply a means of
maintaining documentation in the same source file as the code.
This can negatively affect the understandabili ty of the docs,
especially if the actual code is poorly structured. There is no
magic involved.

--
"If you want to post a followup via groups.google.c om, 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/>

**R.Biloti** · Jan 7 '06, 08:19 AM

Re: Software documentation.. .

barcaroller escreveu:
[color=blue]
> I'm looking for a free software documentation tool that works equally well
> with C and C++. The ones I have found so far with Google are:
>
> - Doxygen
> - Robodoc
> - Natural Docs
>
> There probably are more. Does anyone have any recommendations regarding
> these (and other) software documentation tools?[/color]

I have been using Natural Docs to document my C codes. Its main feature
is that it is **natural**. There is almost no strict syntax to write
the comments NA will parse, so your code remains clean. I have tried
doxygen years before, and NA is definitely better for my purposes.

Cheers,
Ricardo Biloti

**Randy Howard** · Jan 8 '06, 10:05 PM

Re: Software documentation.. .

Chuck F. wrote
(in article <p5ydnUJdIKEpSS PeRVn-qg@maineline.ne t>):
[color=blue]
> Randy Howard wrote:[color=green]
>> jacob navia wrote:
>>[color=darkred]
>>> NO, it is necessary to know what that dammed function DOES and
>>> that will never be written by doxygen or similar tools.[/color]
>>
>> 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.[/color]
>
> As far as I am concerned things like doxygen are simply a means of
> maintaining documentation in the same source file as the code.[/color]

Correct. It is easier to keep the docs in sync with the code
when they are side by side, but still not foolproof.
[color=blue]
> This can negatively affect the understandabili ty of the docs,
> especially if the actual code is poorly structured.[/color]

Even in 2006, there is still no cure for poorly structured code.
Oh well...
[color=blue]
> There is no magic involved.[/color]

Was magic implied?

--
Randy Howard (2reply remove FOOBAR)
"The power of accurate observation is called cynicism by those
who have not got it." - George Bernard Shaw
How 'bout them Horns?

**Chuck F.** · Jan 9 '06, 02:35 AM

Re: Software documentation.. .

Randy Howard wrote:[color=blue]
> Chuck F. wrote:[color=green]
>> Randy Howard wrote:[color=darkred]
>>> 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.[/color]
>>
>> As far as I am concerned things like doxygen are simply a
>> means of maintaining documentation in the same source file as
>> the code.[/color]
>
> Correct. It is easier to keep the docs in sync with the code
> when they are side by side, but still not foolproof.
>[color=green]
>> This can negatively affect the understandabili ty of the docs,
>> especially if the actual code is poorly structured.[/color]
>
> Even in 2006, there is still no cure for poorly structured code.
> Oh well...
>[color=green]
>> There is no magic involved.[/color]
>
> Was magic implied?[/color]

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.c om, 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/>

**Richard Bos** · Jan 9 '06, 08:15 AM

Re: Software documentation.. .

"Chuck F. " <cbfalconer@yah oo.com> wrote:
[color=blue]
> Randy Howard wrote:[color=green]
> > jacob navia wrote:
> >[color=darkred]
> >> NO, it is necessary to know what that dammed function DOES and
> >> that will never be written by doxygen or similar tools.[/color]
> >
> > 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.[/color]
>
> As far as I am concerned things like doxygen are simply a means of
> maintaining documentation in the same source file as the code.
> This can negatively affect the understandabili ty of the docs,[/color]

....and also the understandabili ty of the code...
[color=blue]
> especially if the actual code is poorly structured.[/color]

....especially if the documentation is overly voluble, mixes user-level
descriptions with programmer-aimed explanation, or is simply poorly
written.

Richard

**Randy Howard** · Jan 9 '06, 11:05 AM

Re: Software documentation.. .

Chuck F. wrote
(in article <AIudnb4FgfKkV1 zeRVn-jQ@maineline.ne t>):
[color=blue]
> Randy Howard wrote:[/color]
[color=blue][color=green]
>> It is easier to keep the docs in sync with the code
>> when they are side by side, but still not foolproof.
>>[color=darkred]
>>> This can negatively affect the understandabili ty of the docs,
>>> especially if the actual code is poorly structured.[/color]
>>
>> Even in 2006, there is still no cure for poorly structured code.
>> Oh well...
>>[color=darkred]
>>> There is no magic involved.[/color]
>>
>> Was magic implied?[/color]
>
> 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.[/color]

Oh. That would be silly.
[color=blue]
> That may require several wands.[/color]

Yes.

I find doxygen (and similar tools) to be handy for developing
"man page" type documentation for specific functions, most
usefully with library interfaces.

Overall "user guide" type documentation would be better served
coming about through other means. But to track function
specifics, it is quite useful. It is not an automatic, complete
manual generator, and certainly not without a lot of extra work
in the source file(s).

--
Randy Howard (2reply remove FOOBAR)
"The power of accurate observation is called cynicism by those
who have not got it." - George Bernard Shaw
How 'bout them Horns?

**Michael Wojcik** · Jan 9 '06, 03:35 PM

Re: Software documentation.. .

In article <0001HW.BFE79CD 301A312DBF03865 50@news.verizon .net>, Randy Howard <randyhoward@FO OverizonBAR.net > writes:[color=blue]
> Chuck F. wrote[color=green]
> > Randy Howard wrote:[/color]
>[color=green]
> > 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.[/color]
>
> Oh. That would be silly.[/color]

Indeed (though there will always be plenty of believers in silver
bullets). However, Doxygen will serve as a decent source browser
when run against unannotated source; some people find that useful,
though it has little to do with creating documentation.
[color=blue]
> I find doxygen (and similar tools) to be handy for developing
> "man page" type documentation for specific functions, most
> usefully with library interfaces.[/color]

More generally, source code annotation - except perhaps at the
literate-programming fringe - seems inherently better suited to
producing reference material than introductions, guides, and the
like; it inevitably incorporates some of the structure of the code.
(Literate programming only avoids this problem, if it does at all,
by subordinating the structure of the code to that of the document;
it's debatable whether that's a better trade-off.)

But Doxygen isn't limited to generating documentation from annotated
source code; it can incorporate documentation from separate files,
and there's no reason why you can't use it to prepare non-reference
documentation.

Doxygen is a documentation-preparation system that can derive some
information from source code - no more and no less.

--
Michael Wojcik michael.wojcik@ microfocus.com

I would never understand our engineer. But is there anything in this world
that *isn't* made out of words? -- Tawada Yoko (trans. Margaret Mitsutani)

Software documentation...

Software documentation...

Comment

Comment

Comment

Comment

Comment

Comment

Comment

Comment

Comment

Comment

Comment