Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.c > #93150 > unrolled thread

Doxygen

Back to article view | Back to comp.lang.c

Contents

  Doxygen Malcolm McLean <malcolm.mclean5@btinternet.com> - 2016-09-03 04:13 -0700
    Re: Doxygen Richard Heathfield <rjh@cpax.org.uk> - 2016-09-03 15:51 +0100
      Re: Doxygen David Brown <david.brown@hesbynett.no> - 2016-09-03 18:25 +0200
    Re: Doxygen Randy Howard <rhoward.mx@EverybodyUsesIt.com> - 2016-09-03 13:43 -0500
      Re: Doxygen Ian Collins <ian-news@hotmail.com> - 2016-09-04 08:34 +1200
        Re: Doxygen Malcolm McLean <malcolm.mclean5@btinternet.com> - 2016-09-03 18:10 -0700
          Re: Doxygen Ian Collins <ian-news@hotmail.com> - 2016-09-04 13:41 +1200
          Re: Doxygen Gareth Owen <gwowen@gmail.com> - 2016-09-04 09:05 +0100
        Re: Doxygen Tim Rentsch <txr@alumni.caltech.edu> - 2016-09-04 14:39 -0700
    Re: Doxygen jacobnavia <jacob@jacob.remcomp.fr> - 2016-09-05 00:25 +0200
      Re: Doxygen Gareth Owen <gwowen@gmail.com> - 2016-09-05 06:28 +0100
        Re: Doxygen Gareth Owen <gwowen@gmail.com> - 2016-09-05 07:00 +0100
      Re: Doxygen David Brown <david.brown@hesbynett.no> - 2016-09-05 09:07 +0200
        Re: Doxygen Malcolm McLean <malcolm.mclean5@btinternet.com> - 2016-09-05 00:26 -0700
          Re: Doxygen David Brown <david.brown@hesbynett.no> - 2016-09-05 10:51 +0200
    Doxygen "Rick C. Hodgin" <rick.c.hodgin@gmail.com> - 2016-09-04 17:29 -0700

#93150 — Doxygen

I've been experimenting with Doxygen.

It's produced a nice doc for my binary image library

http://malcolmmclean.github.io/binaryimagelibrary/

Anyone else had any good or bad experiences with it?

[toc] | [next] | [standalone]

#93152

On 03/09/16 12:13, Malcolm McLean wrote:
> I've been experimenting with Doxygen.
>
> It's produced a nice doc for my binary image library
>
> http://malcolmmclean.github.io/binaryimagelibrary/

That's a fairly typical Doxymented project.

> Anyone else had any good or bad experiences with it?

The most important thing about Doxygen output is to think of it as an 
adjunct to the documentation, not a replacement for it.

-- 
Richard Heathfield
Email: rjh at cpax dot org dot uk
"Usenet is a strange place" - dmr 29 July 1999
Sig line 4 vacant - apply within

[toc] | [prev] | [next] | [standalone]

#93154

On 03/09/16 16:51, Richard Heathfield wrote:
> On 03/09/16 12:13, Malcolm McLean wrote:
>> I've been experimenting with Doxygen.
>>
>> It's produced a nice doc for my binary image library
>>
>> http://malcolmmclean.github.io/binaryimagelibrary/
>
> That's a fairly typical Doxymented project.
>
>> Anyone else had any good or bad experiences with it?
>
> The most important thing about Doxygen output is to think of it as an
> adjunct to the documentation, not a replacement for it.
>

You can use Doxygen to make a more complete documentation for your code, 
and it can be quite a good way to make structured documentation 
available in a variety of formats.  But the key point to good Doxygen 
use is to get a suitable balance between documentation and code in the 
code files - and put the larger bits of documentation in separate files. 
  The worst thing you can do with Doxygen is to have headers with dozens 
of lines of Doxygen comments for every couple of lines of declaration. 
If the comments get in the way of reading and understanding the code, 
there are too many and they should be in separate files.

But it is fine for those files to be processed through Doxygen.


Also, for a library it is usual for the Doxygen comments to go mainly in 
the header, not the source files.  Users of the library want to know how 
to use it - they care little for how it is implemented.

[toc] | [prev] | [next] | [standalone]

#93159

On 9/3/16 6:13 AM, Malcolm McLean wrote:
> I've been experimenting with Doxygen.
>
> It's produced a nice doc for my binary image library
>
> http://malcolmmclean.github.io/binaryimagelibrary/
>
> Anyone else had any good or bad experiences with it?
>

It's rather amazing just how poor Doxygen is, given that is
often portrayed as the best of such tools.

It's a difficult thing to automate docs in such a way that
produces good results, stays current and correct with code
changes, and doesn't make the source look horrific.

Unfortunately, doxygen doesn't really address any of those
desires well. That said, nothing else does either, except
manual labor. It's a real problem, and one that doesn't seem
to interest people enough to do well.




-- 
Randy Howard
(replace the obvious text in the obvious way if you wish to contact me 
directly)

[toc] | [prev] | [next] | [standalone]

#93171

On 09/ 4/16 06:43 AM, Randy Howard wrote:
> On 9/3/16 6:13 AM, Malcolm McLean wrote:
>> I've been experimenting with Doxygen.
>>
>> It's produced a nice doc for my binary image library
>>
>> http://malcolmmclean.github.io/binaryimagelibrary/
>>
>> Anyone else had any good or bad experiences with it?
>>
>
> It's rather amazing just how poor Doxygen is, given that is
> often portrayed as the best of such tools.
>
> It's a difficult thing to automate docs in such a way that
> produces good results, stays current and correct with code
> changes, and doesn't make the source look horrific.
>
> Unfortunately, doxygen doesn't really address any of those
> desires well. That said, nothing else does either, except
> manual labor.

Unit tests are the only documentation guaranteed to stay current and 
correct with code changes.

> It's a real problem, and one that doesn't seem
> to interest people enough to do well.

With unit tests, you don't get to choose!

-- 
Ian

[toc] | [prev] | [next] | [standalone]

#93184

On Saturday, September 3, 2016 at 9:34:26 PM UTC+1, Ian Collins wrote:
> On 09/ 4/16 06:43 AM, Randy Howard wrote:
> > On 9/3/16 6:13 AM, Malcolm McLean wrote:
> >> I've been experimenting with Doxygen.
> >>
> >> It's produced a nice doc for my binary image library
> >>
> >> http://malcolmmclean.github.io/binaryimagelibrary/
> >>
> >> Anyone else had any good or bad experiences with it?
> >>
> >
> > It's rather amazing just how poor Doxygen is, given that is
> > often portrayed as the best of such tools.
> >
> > It's a difficult thing to automate docs in such a way that
> > produces good results, stays current and correct with code
> > changes, and doesn't make the source look horrific.
> >
> > Unfortunately, doxygen doesn't really address any of those
> > desires well. That said, nothing else does either, except
> > manual labor.
> 
> Unit tests are the only documentation guaranteed to stay current and 
> correct with code changes.
> 
> > It's a real problem, and one that doesn't seem
> > to interest people enough to do well.
> 
> With unit tests, you don't get to choose!
> 
How would you set up unit tests for the binary image processing library?

The functions have been tested, of course, but generally I've done it
by visual inspection of output.

[toc] | [prev] | [next] | [standalone]

#93185

On 09/ 4/16 01:10 PM, Malcolm McLean wrote:
> On Saturday, September 3, 2016 at 9:34:26 PM UTC+1, Ian Collins wrote:
>> On 09/ 4/16 06:43 AM, Randy Howard wrote:
>>> On 9/3/16 6:13 AM, Malcolm McLean wrote:
>>>> I've been experimenting with Doxygen.
>>>>
>>>> It's produced a nice doc for my binary image library
>>>>
>>>> http://malcolmmclean.github.io/binaryimagelibrary/
>>>>
>>>> Anyone else had any good or bad experiences with it?
>>>>
>>>
>>> It's rather amazing just how poor Doxygen is, given that is
>>> often portrayed as the best of such tools.
>>>
>>> It's a difficult thing to automate docs in such a way that
>>> produces good results, stays current and correct with code
>>> changes, and doesn't make the source look horrific.
>>>
>>> Unfortunately, doxygen doesn't really address any of those
>>> desires well. That said, nothing else does either, except
>>> manual labor.
>>
>> Unit tests are the only documentation guaranteed to stay current and
>> correct with code changes.
>>
>>> It's a real problem, and one that doesn't seem
>>> to interest people enough to do well.
>>
>> With unit tests, you don't get to choose!
>>
> How would you set up unit tests for the binary image processing library?
>
> The functions have been tested, of course, but generally I've done it
> by visual inspection of output.

I would have used a mixture of unit tests for the code (it would have 
been written with TDD) and something like expect as for user acceptance 
tests.  I ran a project a while back where we had an embedded display 
and our testers used expect with reference bitmaps for acceptance testing.

-- 
Ian

[toc] | [prev] | [next] | [standalone]

#93188

Malcolm McLean <malcolm.mclean5@btinternet.com> writes:

>> With unit tests, you don't get to choose!
>> 
> How would you set up unit tests for the binary image processing library?
>
> The functions have been tested, of course, but generally I've done it
> by visual inspection of output.

I've done unit-tests on FPGA implementations of image-processing. Once
you've generated "golden" output files, you just need to check that your
conversions match them - either identity for lossless transformations,
or some RMS/Max-error criteria for lossy transformations (I think YUV
colorspace is better for these checks).  

It's imperfect, but it does catch most of your errors.

[toc] | [prev] | [next] | [standalone]

#93195

Ian Collins <ian-news@hotmail.com> writes:

> On 09/ 4/16 06:43 AM, Randy Howard wrote:
>> On 9/3/16 6:13 AM, Malcolm McLean wrote:
>>> I've been experimenting with Doxygen.
>>>
>>> It's produced a nice doc for my binary image library
>>>
>>> http://malcolmmclean.github.io/binaryimagelibrary/
>>>
>>> Anyone else had any good or bad experiences with it?
>>
>> It's rather amazing just how poor Doxygen is, given that is
>> often portrayed as the best of such tools.
>>
>> It's a difficult thing to automate docs in such a way that
>> produces good results, stays current and correct with code
>> changes, and doesn't make the source look horrific.
>>
>> Unfortunately, doxygen doesn't really address any of those
>> desires well.  That said, nothing else does either, except
>> manual labor.
>
> Unit tests are the only documentation guaranteed to stay current and
> correct with code changes.

Not true.  A counterexample is assertions.

[toc] | [prev] | [next] | [standalone]

#93198

Le 03/09/2016 à 13:13, Malcolm McLean a écrit :
> I've been experimenting with Doxygen.
>
> It's produced a nice doc for my binary image library
>
> http://malcolmmclean.github.io/binaryimagelibrary/
>
> Anyone else had any good or bad experiences with it?
>

I have never used it. Maybe because I was so frustrated when I opened a 
directory called "doc" and found just a bunch of doxygen generated html 
and no documentation.

Yes, you can read doxygen if you can't sleep. BBut for all other 
purposes the output is just a simple repetition of what you can already 
read in the code. That is no DOCUMENTATION in the sense that doesn't 
explain anything, nor does it describe the architecture of the system.

It is just machine generated verbiage that nobody reads.

[toc] | [prev] | [next] | [standalone]

#93203

jacobnavia <jacob@jacob.remcomp.fr> writes:

> That is no DOCUMENTATION in the sense that doesn't explain anything,
> nor does it describe the architecture of the system.

You can, of course use Doxygen to generate such documentation, but you
still have to write it by hand, which is the major sticking point.

> It is just machine generated verbiage that nobody reads.

A lot of it, yes.  I find @brief, @param and @returns useful, though.
More often than note, I just find the discipline to include them in the
headers extremely useful.  I rarely actually run Doxygen for the HTML;
only because it will tell me which functions I haven't documented in
this way.

It's just a nice, moderately "standard", way to document function
parameters, and to check that its done.

[toc] | [prev] | [next] | [standalone]

#93205

Gareth Owen <gwowen@gmail.com> writes:

> jacobnavia <jacob@jacob.remcomp.fr> writes:
>
>> That is no DOCUMENTATION in the sense that doesn't explain anything,
>> nor does it describe the architecture of the system.
>
> You can, of course use Doxygen to generate such documentation, 

This is very poorly phrased - I guess I mean "format and integrate such
documentation"

[toc] | [prev] | [next] | [standalone]

#93212

On 05/09/16 00:25, jacobnavia wrote:
> Le 03/09/2016 à 13:13, Malcolm McLean a écrit :
>> I've been experimenting with Doxygen.
>>
>> It's produced a nice doc for my binary image library
>>
>> http://malcolmmclean.github.io/binaryimagelibrary/
>>
>> Anyone else had any good or bad experiences with it?
>>
> 
> I have never used it. Maybe because I was so frustrated when I opened a
> directory called "doc" and found just a bunch of doxygen generated html
> and no documentation.
> 
> Yes, you can read doxygen if you can't sleep. BBut for all other
> purposes the output is just a simple repetition of what you can already
> read in the code. That is no DOCUMENTATION in the sense that doesn't
> explain anything, nor does it describe the architecture of the system.
> 
> It is just machine generated verbiage that nobody reads.

What you get out of doxygen is entirely dependent on what you put in.  I
have not used it on many projects, but I've done so on a few.  And I've
found it useful to include text files and diagrams (using graphviz) to
give more information about the code than is sensible to have as normal
comments.

If you are using doxygen just alongside comments in the code, then
clearly it is not adding any new information - because doxygen does not
create documentation or information, it merely presents it.  But even
then, you are getting the information in a new way with a different
emphasis - a focus on the comments rather than on the code.  That can be
useful.

Additionally, doxygen can give useful tools such as call graphs, include
hierarchies, clickable cross-references, etc.  I've found that quite
useful when trying to understand a new body of code, especially one with
poor comments or documentation (i.e., just about /any/ code - except my
own, of course :-) ).  When you are trying to understand what the
function "foo" is for, a cross-reference showing call graphs, the
source, and all uses of the function is very helpful.

[toc] | [prev] | [next] | [standalone]

#93213

On Monday, September 5, 2016 at 8:07:34 AM UTC+1, David Brown wrote:
> On 05/09/16 00:25, jacobnavia wrote:
> 
> > It is just machine generated verbiage that nobody reads.
> 
> What you get out of doxygen is entirely dependent on what you put in.  I
> have not used it on many projects, but I've done so on a few.  And I've
> found it useful to include text files and diagrams (using graphviz) to
> give more information about the code than is sensible to have as normal
> comments.
> 
> If you are using doxygen just alongside comments in the code, then
> clearly it is not adding any new information - because doxygen does not
> create documentation or information, it merely presents it.  But even
> then, you are getting the information in a new way with a different
> emphasis - a focus on the comments rather than on the code.  That can be
> useful.
>
It's inherently impossible for a computer program to add any information,
unless you solve the natural language problem and program something
like R2D2 from Star Wars. (He died recently, but he was a much better 
actor than C3PO, until I read the obituary I never realised that R2D2
was a man dressed up, though I should have guessed - it would be hard to
get even a human-directed radio model to behave like that).
>
> Additionally, doxygen can give useful tools such as call graphs, include
> hierarchies, clickable cross-references, etc.  I've found that quite
> useful when trying to understand a new body of code, especially one with
> poor comments or documentation (i.e., just about /any/ code - except my
> own, of course :-) ).  When you are trying to understand what the
> function "foo" is for, a cross-reference showing call graphs, the
> source, and all uses of the function is very helpful.
>
This is it. I've been meaning to document the binary image library
for a long time. But the web documentation is stuck on site 11.
I tried to download it as zip, and all the gif files were broken.

With doxygen, you just format the comments and press go.
But I think the document could be nicer. An image-based library
should have images in the docs.

[toc] | [prev] | [next] | [standalone]

#93218

On 05/09/16 09:26, Malcolm McLean wrote:
> On Monday, September 5, 2016 at 8:07:34 AM UTC+1, David Brown wrote:
> This is it. I've been meaning to document the binary image library
> for a long time. But the web documentation is stuck on site 11.
> I tried to download it as zip, and all the gif files were broken.
> 
> With doxygen, you just format the comments and press go.
> But I think the document could be nicer. An image-based library
> should have images in the docs.
> 

Just put images in your folders somewhere, and add references to the
doxygen documentation.  Then you get images in the generated output.

You are not limited to plain text as you are will normal C comments.

[toc] | [prev] | [next] | [standalone]

#93199

Malcolm MacLean wrote:
> Anyone else had any good or bad experiences with [Doxygen]?

I have found it to be wonderful.  It served as a major source of
input for my documentation mechanism, called "SourceLight."

Best regards,
Rick C. Hodgin

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.c

csiph-web