doxygen-users

[Doxygen-users] more odd behavior

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

what causes this?

there is a
structure  control
	{
int V1;
int V2;
};

a declaration
struct control control_arrays;

within a function, a declaration of a pointer to the structure

struct control * table_pointer;

	table_pointer=control_arrays
i.e. a pointer is set to point to a control structure, called   control_arrays

	there is a reference to
           table_pointer->V1

This gets put in the HTML as
     control::V1

First of all, this is NOT a reference to control directly.  it 
is      table_pointer->V1
So what should be put in front of the function is

     table_pointer->V1        which is the reference used in the function, not
     control::V1                  which is a class member, and there are no 
classes here.
Once again, there is a disconnect between *what is used in the function* 
and what doxygen picks up.  Yes, doxygen figures out that table_pointer 
points to a control structure, but since this is NOT C++, and there are NO 
classes defined, it should NOT use a C++ type indentifier.
What this has forced me to do, since doxygen is failing to put the 
references into the .rtf file,
is to go to the HTML docs, copy the   "Refers to   section, paste that into 
notepad, and reselct it  and copy it to the the clipboard, to get rid of 
the linkages, so it is straight text, then past it into the RTF file.
THEN I have to take a lot of time to correct it so it actually documents 
what is in the function.

I find this not only puzzling, but very frustrating.

Why isn't this thing smart enough to actually use what is in the function 
when producing documentation.

Perhaps it needs a set of options     use only C syntax, and use 
descriptions from within the function body, and use the actual function 
header rather than the prototype.

Re: [Doxygen-users] more odd behavior

[Monique S. <mon...@ea...>]

> Perhaps it needs a set of options     use only C syntax, and use
descriptions from within the function body, and use the actual function
header rather than the prototype.

I don't know if it will take care of the specific issues that you've been 
describing, but there is (in Doxygen 1.8.10, and I think for many, many 
earlier versions) an option in the Doxygen config file, 
OPTIMIZE_OUTPUT_FOR_C.

Perhaps that will help?

-Monique 

Re: [Doxygen-users] more odd behavior

[Brian H. <bhe...@pi...>]

Woody,

Doxygen does not write documentation for you; it formats and cross-references documentation you have written.

Doxygen generating a cross-reference to "control::V2" (which is a common convention to referring to a struct type member[1]) for the expression table_pointer->V2 is exactly what it's supposed to do.  

If you disagree, please provide actual samples, e.g. the content you are feeding to Doxygen and the output it is generating, along with an example of what you want it to generate.  There may yet be a way to achieve your goals.

Regards,
-Brian

[1] C does not have a language construct for referring to a member of a type because it's unnecessary; there's no such thing as inheritance or polymorphism in the language like there is in C++.  In C++, you very well might have to fully-qualify a member to access it.  Consider:

   typedef struct {
      int V1;
   } control;

In C++, you could write sizeof(control::V1) and get back the same as if you wrote sizeof(int)--you are referring to the type directly, not an instance of the type.  In code terms, you could do something like this:

  assert(sizeof(control::V1) == sizeof(int)); // Fail mightily if someone redefines V1

That would not be possible in C.  You would have to have an instance, like so:

   control one_of_them;
   assert(sizeof(one_of_them.V1) == sizeof(int));

Or you could get clever and do this to save stack:

   assert(sizeof(((control *)0)->V1) == sizeof(int));