Thread: Re: [Doxygen-users] adding doxygen comments to code

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

At 01:49 AM 6/26/2015 -0400, you wrote:
>Woody,
>I would strongly disagree about adding that functionality directly into 
>doxygen. In its normal usage, it totally should not be changing the source 
>base, and for that to happen with just an option change. The code to add 
>the comment frames into the source files would be a much simpler program 
>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.

  I'm kind of comparing what the old c-doc did.  For a large program that 
does not have doxygen headers,
it would take a large amount of time to go through and add them.  Doxygen 
*could* create a diff-merge file though pretty easily.
It would not add the comments to the source, just make a file that could be 
run through a diff merger.

Cdoc would do this for you, but it was an option to add the comments to the 
file.  typically you did it once.  As you can see, this was done back
in 2004.  The code is now 11 years old, and this has never been updated, 
primarily because C-Doc isn't around any more.:, secondarily because I
don't have the documentation for the version of C-Doc that I  do have.

Of course, this isn't doxygen compliant, obviously, since doxygen wasn't 
around in the 1980's when C-Doc was first created.

/*FF***********************************************************************
FUNCT: update_intensity                                  2004/09/22 14:29
                                   USERS:
                                          main 

                                          update_current_values 

                                   DEFIN:
                                          INTENSITY_ALLOWED 

                                          INTENSITY_MODIFY 

                                          INTENSITY_OVERIDE 

                                          USER_MAX_INTS 

                                   GLOBL:
                                          control_arrays.intensity_array 

                                          control_arrays.permission 

                                          control_arrays.table_pointer 

                                          control_arrays.table_pointer->intensity_maximum 

                                          control_arrays.table_pointer->intensity_minimum 

                                          control_arrays.table_pointer->intensity_type 

                                          current_intensity 

                                          current_user_intensity 

                                   PARAM:
                                          flags 

                                          next_entry 

                                   LOCAL:
                                          permit 

**************************************************************************/

>I will point out a big reason I don't think you want to do this. Doxygen 
>is fully capable of generating the documentation for objects without the 
>comments being present, and can also generate a list of warning for items 
>that it created documentation without comments.

I have not seen it do any warnings like that todate

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

>  Having the undocumented warning is a good way to get a task list of 
> stuff that you want to go in to improve. If you automatically add the 
> comments, the warnings go away and you need to do something else to keep 
> track of what is needed to improve the entries.

I would disagree, once the comments are added, and you have the result, 
then it would be a magnitude easier to tweak them until they were fine.
You could always run it once, and save the warning file, then add the 
comments in.  You can always refer to the warning file to go in and clean 
things up,
but the tool would have saved potentially hundreds of man-hours of time.

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.

I've been writing code since 1976 for micros, and have made a career as a 
temp.  Ninety percent of the time, I would be coming in to
rescue a project where the original programmer left and/or is not 
contactable (in one case he was in a mental institution, I kid you 
not).  So you take the code, and run it through whatever tools you have so 
you can pick up and go.  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.  C-Doc doesn't 
exist any more, (though I have an old copy), and no one has the key for the 
newer copy.  Additionally without any kind of manual, it is pretty hard to 
get the options right.

In this case *I* wrote the code over the past 10 years, and now it needs to 
be put in shape so someone coming in can maintain it, cause I'm looking 
retirement in the face.  That and we need to document an architecture for 
IEC 62304 compliance.  (this is code for
a FDA cleared micro-current tens unit).

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

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.

I have two different structures with a common header.  I have a structure 
that just has the common header.  So I can tell the compiler
to point to the common structure, and information in the common structure 
area will identify which structure it is, so the run time can
know how to handle it.  Yes it is weird, but it solved a batch of 
"incompatible  pointer" problems....

What I have been trying to get it to do is something like this

           -------------[update_parameters]
           |                                |
           |                                --------[calls function 2]
           |                                |____[calls function 2]
           |                                             |____ [calls 
function 4]
           |
main- |
          | ---- [calls button scan]
          |------[calls function 5]
          |

etc.  the editor I use   Source Insight (one of the best editors on the 
planet in my opinion) will do this, but you have to save screen shots.  and 
by the way,
it has a free trial.  This feature is the relationship window.  You can 
have multiple windows, each with a different relationship and when you 
click on a symbol in the code, it will generate a nice graphic for 
you.  Quite impressive.

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

>--
>Richard Damon

Thread: Re: [Doxygen-users] adding doxygen comments to code

doxygen-users