Re: [Doxygen-users] Another question....

[Frank P. <f2...@ei...>]

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; the people working on the 
function body can read the code. People using the function can see the 
.h file, which has the prototype, 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
>
>
> _______________________________________________
> Doxygen-users mailing list
> Dox...@li...
> https://lists.sourceforge.net/lists/listinfo/doxygen-users