Forward struct references. playing nicely with automatic documentation?

[mathog]

Typically I do forward references to struct like this:

typedef struct is_TYPE1 TYPE1; // forward reference for section 1.2.20

// code

typedef struct { // section 1.2.3
TYPE1 name;
} TYPE2;

// more code

struct is_TYPE1 { // section 1.2.20
int a;
float b;
};

The problem is that when this is run through doxygen the "is_TYPE1" is
exposed in the documentation. Ideally the structs would all be
declared in a particular order (corresponding to their section numbers
in the specification, as indicated in the comments).

At present I deal with this by rearranging the code to eliminate the
forward references:

typedef struct { // section 1.2.20, out of order, needed for TYPE2
int a;
float b;
} TYPE1;

// code

typedef struct { // section 1.2.3
TYPE1 name;
} TYPE2;

// more code

// struct TYPE1, section 1.2.20, implemented out of order, above

This goes through the documentation generator cleanly, and even though
everything is not strictly in the section order, at least the exceptions
are all documented where they occur.

Is there a better way to do this?

Thanks,

David Mathog

 

[Eric Sosman]

Typically I do forward references to struct like this:

typedef struct is_TYPE1 TYPE1; // forward reference for section 1.2.20

// code

typedef struct { // section 1.2.3
TYPE1 name;

What do you do about the diagnostic message, typically?

} TYPE2;

// more code

struct is_TYPE1 { // section 1.2.20
int a;
float b;
};

The problem is that when this is run through doxygen the "is_TYPE1" is
exposed in the documentation. Ideally the structs would all be
declared in a particular order (corresponding to their section numbers
in the specification, as indicated in the comments).

At present I deal with this by rearranging the code to eliminate the
forward references:

typedef struct { // section 1.2.20, out of order, needed for TYPE2
int a;
float b;
} TYPE1;

// code

typedef struct { // section 1.2.3
TYPE1 name;
} TYPE2;

// more code

// struct TYPE1, section 1.2.20, implemented out of order, above

This goes through the documentation generator cleanly, and even though
everything is not strictly in the section order, at least the exceptions
are all documented where they occur.

Is there a better way to do this?

Sounds like a doxygen question, not a C question. Basically,
you want to suppress some information about a type (the struct tag)
while allowing other stuff to show up in the document. So, your
problem is "How do tell doxygen to omit something?" not "How do I
get the C language to do something?"

http://sourceforge.net/mail/?group_id=5971 is a doxygen
mailing list. Try asking there.

 

[glen herrmannsfeldt]

Typically I do forward references to struct like this:

typedef struct is_TYPE1 TYPE1; // forward reference for section 1.2.20
(snip)

The problem is that when this is run through doxygen the "is_TYPE1" is
exposed in the documentation. Ideally the structs would all be
declared in a particular order (corresponding to their section numbers
in the specification, as indicated in the comments).

At present I deal with this by rearranging the code to eliminate the
forward references:

I was guessing that the preprocessor would be used, but it seems
that is the traditional method. The new method is with the
\cond and \endcond commands.

That is, you tell doxygen to ignore the parts you want it to ignore.

-- glen

 

[glen herrmannsfeldt]

On 5/30/2013 12:54 PM, mathog wrote:
(snip)
(snip)

Sounds like a doxygen question, not a C question. Basically,
you want to suppress some information about a type (the struct tag)
while allowing other stuff to show up in the document. So, your
problem is "How do tell doxygen to omit something?" not "How do I
get the C language to do something?"

Seems so, but you can also use the C language, specifically the
preprocessor, to do it. Putting something inside #ifndef and then
defining the preprocessor symbol to doxygen is one of the
suggested ways. I would call that using the C language.

-- glen

 

[Ivan Shmakov]

[...]

At present I deal with this by rearranging the code to eliminate the
forward references:

typedef struct { // section 1.2.20, out of order, needed for TYPE2
int a;
float b;
} TYPE1;

// code

typedef struct { // section 1.2.3
TYPE1 name;
} TYPE2;

// more code

// struct TYPE1, section 1.2.20, implemented out of order, above

This goes through the documentation generator cleanly, and even
though everything is not strictly in the section order, at least the
exceptions are all documented where they occur.

Is there a better way to do this?

I understand that this may not be a feasible solution in a
particular case, but personally, I'd just omit typedefs, and use
plain structs, thus avoiding the necessity of a "duplicate"
identifier (for either the struct or the typedef.) Like:

struct STRUCT1;

struct STRUCT2 { // section 1.2.3
struct STRUCT1 name;
};

struct STRUCT1 { // section 1.2.20
int a;
float b;
};

(Please note, however, that I'm not familiar with Doxygen, and
do not know how it would handle the advance struct STRUCT1
declaration above.)

 

[Eric Sosman]

Seems so, but you can also use the C language, specifically the
preprocessor, to do it. Putting something inside #ifndef and then
defining the preprocessor symbol to doxygen is one of the
suggested ways. I would call that using the C language.

I doesn't seem that way to me.

When you write something like /*NOTREACHED*/ you are, in a sense,
"using the C language:" You are using it to write a comment. But the
comment's significance has nothing to do with C, and everything to do
with a tool that reads C source for its own non-C purposes. If you
wrote /* NOT REACHED */ instead, the comment would still be perfectly
good C, even if it was "wrong" for the tool. It's not C's rules that
determine the comment's rightness or wrongness, so writing the comment
properly is about using the tool, not about using C.

That's exactly how doxygen-formatted comments work, and (I
guess) what #ifndef doxygen does: When compiling the code you'll
make sure there's no `doxygen' preprocessor symbol defined, so
the #ifndef and its matching #endif simply disappear from the
module with no effect on the meaning of the C. And when running
the code through doxygen you'll make sure there *is* a `doxygen'
symbol, so the tool sees a slightly different source than does
the compiler (an invalid C source, at that).

Writing a bunch of tokens that make no difference to the
meaning of the program is not (IMHO) "using the C language;" it's
hiding non-C directives inside C source, and the effect of those
directives as seen by C is precisely nil. You could call it
steganography, I guess -- and you could call it useful in
connection with the non-C tool -- but I can't agree with calling
it "C." It's tool-speak, and problems with it are best answered
in tool-forums.

 

[glen herrmannsfeldt]

(snip)

(snip)

I doesn't seem that way to me.

The OP wants to hide a legal C statement. Using the C preprocessor
to do it, just as you might want to hide one from the C compiler,
seems to me using C.

If you hide other than legal C statements, then I agree that it
isn't C.

doxygen commands are usually written in special C comments, such
as ones starting with /**. (There are options for languages that
don't use C-style comments.)

One fun thing about the C preprocesor is that you can hide all
kinds of stuff that isn't legal C. Partially written C code might
be an obvious choice, but a lot more.

When you write something like /*NOTREACHED*/ you are, in a sense,
"using the C language:" You are using it to write a comment. But the
comment's significance has nothing to do with C, and everything to do
with a tool that reads C source for its own non-C purposes. If you
wrote /* NOT REACHED */ instead, the comment would still be perfectly
good C, even if it was "wrong" for the tool. It's not C's rules that
determine the comment's rightness or wrongness, so writing the comment
properly is about using the tool, not about using C.

I suppose some might write NOTREACHED even when it was to be
read by a human, but yes programs sometimes expect things to
be done in specific ways. If it said:

/* the following statements are never executed by this program */

is it using C or not?

That's exactly how doxygen-formatted comments work, and (I
guess) what #ifndef doxygen does: When compiling the code you'll
make sure there's no `doxygen' preprocessor symbol defined, so
the #ifndef and its matching #endif simply disappear from the
module with no effect on the meaning of the C. And when running
the code through doxygen you'll make sure there *is* a `doxygen'
symbol, so the tool sees a slightly different source than does
the compiler (an invalid C source, at that).

Or maybe just a different valid C source.

Writing a bunch of tokens that make no difference to the
meaning of the program is not (IMHO) "using the C language;" it's
hiding non-C directives inside C source, and the effect of those
directives as seen by C is precisely nil. You could call it
steganography, I guess -- and you could call it useful in
connection with the non-C tool -- but I can't agree with calling
it "C." It's tool-speak, and problems with it are best answered
in tool-forums.

-- glen

 

[Martin Shobe]

(snip)


The OP wants to hide a legal C statement. Using the C preprocessor
to do it, just as you might want to hide one from the C compiler,
seems to me using C.

But a tool might not even use the C preprocessor, so whether or not
using #ifndef (or similar trick) even works is completely up to the tool.

If you hide other than legal C statements, then I agree that it
isn't C.

If I understand the situation correctly, what is getting passed to
doxygen isn't legal C statements. But that's okay since doxygen isn't C.

[snip]

Martin Shobe