At 09:00 AM 9/4/2015 +0100, Frank Peelo wrote:
If you're really going to have different parameter names, the ones in the
header should be the ones documented. The documentation is for people who
are going to use the function;
Precisely, that is why it should be the FUNCTION ACTUAL HEADER
the people working on the function body can read the code. People using
the function can see the .h file, which has the prototype,
Nope. In this case the prototype is in the C code. The target audience
for this documentation is management.
HOWEVER: In this case, what they will see is not the C code, but a detailed
verbal english description of the code. (My boss refuses
to learn any C code, yet he wants a detailed spec specifying what the
program is doing in English.)
The html however, will allow direct access to the body of the file, and
when it says that
for function foo the input parameters are int offtime and offtime is
not used or referenced in the code, then that is a problem.
The "references" section of the html header lists all references used in
the module. When it says off and there is no off in the
code, nor in the header, that sends you off on a tangent trying to find
where in the hell off is in the code.
So the parameter list that is in the documentation for the specific
function, SHOULD match the function, or it leads to confusion.
The disconnect is that it uses the prototype and states that those
parameters are used in the function, when indeed, there may not be ANY
values with that name.
Consider this:
foo (int, int,int,char); // a prototype with no identifiers, which is
quite legal
foo (int time, int off, int on, char flag)
The current way of doing it would result in
foo
int
int
int
Which does not help with understanding the function. In this case it should be
foo
int time
int off
int on
char flag
so doxygen SHOULD use the actual name in the function, not the prototype,
because the prototype can be written with NOT NAME AT ALL for the parameters.
and may not have access to the .c code; if they do have that, they
shouldn't need to read it. So Doxygen *should* use the names in the
prototype, instead of the ones in the .c file.
Frank
On 03/09/15 21:16, woody wrote:
It seems that Doxygen uses the prototype definition when it creates
documentation for a function in the html and rtf files.
For example,
The actual definition of initiate_beep
static void initiate_beep (int duration,int off, char count)
{
// code body
}
the prototype:
static void initiate_beep (int duration,int offtime,char count);
The compiler is just fine with this, because all it cares about is the
type. However, doxygen picks up the prototype, and uses that as the
header for the html and in the rtf file,
and puts only the body of the code under the header, showing the
prototype as the parameters, which of course can cause problems in
understanding and documenting code if the programmer
used different names for the same type.
of course in the body of the code, it is just off so *really*
doxygen SHOULD be using the actual function definition, if there is one.
that is, if there is a function that matches the prototype as far as
variable types, then the definition line where the function is actually
found, should be used to
show the calling parameters, not the prototype.
This is easy to check. Just create a function and a prototype, use
different names for the same type parameters, and run through doxygen.
Doxygen should document code *as written* or in construction terms "as
built" rather than "as planned".
prototypes are "as planned" items, actual functions are "as written".
And YES, before anyone says anything else, IT IS BAD PRACTICE to use
variable names that are different between function and prototype....
------------------------------------------------------------------------------
Monitor Your Dynamic Infrastructure at Any Scale With Datadog!
Get real-time metrics from all of your servers, apps and tools
in one place.
SourceForge users - Click here to start your Free Trial of Datadog now!
<http://pubads.g.doubleclick.net/gampad/clk?id=241902991&iu=/4140>http://pubads.g.doubleclick.net/gampad/clk?id=241902991&iu=/4140
_______________________________________________
Doxygen-users mailing list
<mailto:Doxygen-users@lists.sourceforge.net>Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
------------------------------------------------------------------------------
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
------------------------------------------------------------------------------
_______________________________________________
Doxygen-users mailing list
Doxygen-users@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/doxygen-users
