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
------------------------------------------------------------------------------
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
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
