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

[woody <kn...@re...>]

>
>
>
>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.

Sound like it.  I know nothing about XML unfortunately :(



>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.

I agree. I *has* to have the information though, whether or not it 
organizes it.  When it scan a program, indentifies a symbol, it reports 
which line the symbol is defined on.  It could and should
also have an option to report ALL the lines.  I would think it would be a 
"simple" [I know, there are NO simple program changes :) ]  matter to 
attach to the defined line, another data structure that would
contain a line number for each non comment line that it finds the 
symbol.  It might just be a matter of making a linked list of line numbers, 
using the defined line as the head of the list, and just adding to
it as lines are found.


> >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.

Well, consider the issue raised :D .  It just seems obvious.

>Â
>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".

Absolutely.  Once that is done, then going back and maintaining the 
comments will be much easier, and the documentation will be much nicer.


>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.

You might, but they would just be padding on existing lines more or 
less.  So yes, but it is a lot easier and quicker to go into the code and 
add the comments or descriptive prose to an
existing comment block.   1. You don't have to remember how to create the 
block.   2. with the blocks in place, documentation would certainly be easier.

My way of looking at code is that it is the crystallized thoughts and 
thought process of the programmer.  One should write code for the guy 
coming behind.  The compiler doesn't care about comments
and will generate the code regardless of comments.  But comment blocks etc, 
especially of the kind that Doxygen uses would be very helpful.

One of the things coming down in the medical device world, is compliance 
with IEC 62304.  One part of this requires detailed 
architectural  descriptions and diagrams.  Current code will ultimately
have to be brought up to that standard, and all over the medical world, 
people are having to back document programs.

>Â
>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.

I have attached a file, and hope it comes through.

This file was generated by Source Insight, the source editor I use.  Ray 
Grahm has done a fantastic job with this tool.   This is the kind of 
diagram that I would like to be able to generate via Doxygen and
other tools.

The problem with doing this with Source Insight, is that you have to click 
on one variable at a time, and then do a screen capture.  It is fraught 
with problems.  missing one, the long manaul series of
operations, and on and on.
Notice that this produces the kind of "flow" diagram needed.

current_intensity is the variable.  This shows that build_array uses it, as 
do a bunch of the routines that build array calls.
There are many other places in the code where this variable are referenced.

Doxygen has the info to do this, or would with an extension.  I was hoping 
that graphvis would be able to take Doxygen's data
and produce this kind of diagram automatically for each function, variable, 
and data structure.



>------------------------------------------------------------------------------
>Monitor 25 network devices or servers for free with OpManager!
>OpManager is web-based network management software that monitors
>network devices and physical & virtual servers, alerts via email & sms
>for fault. Monitor 25 devices for free with no restriction. Download now
>http://ad.doubleclick.net/ddm/clk/292181274;119417398;o_______________________________________________
>Doxygen-users mailing list
>Dox...@li...
>https://lists.sourceforge.net/lists/listinfo/doxygen-users