Re: [Doxygen-users] Doxygen-users Digest, Vol 109, Issue 5

[Ron W <ron...@gm...>]

On Fri, Jun 26, 2015 at 11:46 AM, <
dox...@li...> wrote:
>
> Date: Fri, 26 Jun 2015 10:45:54 -0500
> From: woody <kn...@re...>
> Subject: Re: [Doxygen-users] adding doxygen comments to code
> To: Richard Damon <Ri...@Da...>,
>         dox...@li...
> Message-ID: <4.3...@ma...>
> Content-Type: text/plain; charset="us-ascii"
>
> At 01:49 AM 6/26/2015 -0400, Richard Damon <Ri...@Da...
> > wrote:
> >than doxygen itself, and if such a feature was added, having a separate
> >executable makes much more sense to me.
>
> That sounds logical, which is why I said, "have it generate a diff-merge"
> file that can be run through a diff merger.
>

Doxygen can produce and XML file containing the information it extracted
and/or derived from the source files. With out testing, I don't know if
contains any line numbers. (This is intended to be used by "add on" report
generators.)

Anyway,  it should be possible to create a "post processor" that would read
this XML and generate, for example, a set of sed scripts that could insert
comment blocks into copies of your source files.

>  If the default documentation is good enough,
>
> It really isn't.  There are lots of holes that I see so far, including no
> cross reference that gives you all the line numbers where a symbol is
> used.


This is a separate issue. I don't think Doxygen has any option to generate
a cross reference. If it does, Then it certainly should also have an option
to produce it as part of a "document all" operation.


> Especially global variables. I know Doxygen has all the information
> to do that.    Other holes I know Doxygen could fill in with the proper
> headers, but the syntax of the headers is obtuse at best, and would take a
> huge amount of time to manually add to any non-trivial program,.
>
> >you don't need to add the comments to the code to get them (but I think
> >normally you want to go in and improve on them).
>
> yes, but on a multi thousand line code base that would be very expensive in
> terms of time and money.  It seems so logical to have Doxygen be able to
> do it
> for you on a one time basis to get a start.  It baffles me that it
> can't.  It certainly has the information.  It would make it a much more
> complete documentation tool.
>

Because Doxygen doesn't need comments to produce the default documentation,
nobody saw a need to create an "add on" to automatically insert comment
blocks.


> Here is the problem.  The major use case for doxygen is to come in behind
> some guy who wrote a bunch of code, and gain
> some idea of how the code works, so you can maintain it, and create a
> documentation package for it.

...

> Doxygen is most of the way there, but it
> desperately needs a way to be able
> to insert the comments it can generate, into the source.
>

>From looking at the "C Doc" generated comment sample you provided, you
appear to want Doxygen (or an add on to Doxygen) to insert the generated
pieces of documentation into comment blocks before each function, global
variable and other "document-able objects".

A tool to do this (based on information extracted by Doxygen) could
certainly be made.

I would have to do extensive editing to the code to embed the comments
> that doxygen can use to create the documentation correctly.
>

Even after comments blocks are automatically inserted, I would think you
will still have to do extensive editing to include descriptive prose.


> I have yet to get doxygen to do a flow tree, though I have enabled the
> "dot" stuff and have graphviz in the path.  It created flows only
> for certain structures, and those are really not right.
>

Doxygen really only "creates" call graphs and a few other basic
relationship graphs. It was not intended as a source code analyzer.


> I am aware that *IF* you have the right headers, Doxygen can do this and a
> whole lot more.
>

I'm not sure how much of the needed information would (or could) be in
Doxygen's output to create comment blocks with the "fields" needed.
Enhancing Doxygen to generate a cross reference seems reasonably possible.
But, as I said above, Doxygen was not intended to be a source code
analyzer. Output from a proper source code analyzer may also be needed.