At 03:38 PM 9/4/2015 +0000, you wrote:
>Content-Language: en-US
>Content-Type: multipart/alternative;
>
>boundary="_000_acddece4335344f69994c1160549d3aePineMailboxLANGROUPloca_"
>
> From the peanut gallery: Seems to me a reasonable thing to have as an
> option in the doxygen configuration, the option for parameter names to be
> taken from the definition rather than the prototype. With that said, the
> \param special command s first argument is the parameter name. I haven t
> tried it, but it seems that you could specify the name you want used.
>
>
>
>Also as you noted yourself at the start, differing parameter names between
>prototype and definition is a bad practice which harms both usability and
>maintainability. Why is it being done?
Because I wrote this code long ago, when I was not thinking about it....
> Users of a function ought to be looking at the prototype, not the
> definition, so if anything, the prototype ought to have the more
> appropriate names.
I really disagree with this. I'm oldschool, anti- C++. I absolutely hate
relying on anyone elses code. I want the full source, so I can see what is
going on, remove bloat etc.
Because I work in the deep embedded at the metal level, memory size is
crucial. So I am not going to be looking at the prototype. Indeed the
only use I have for prototypes is as a quick
way to jump to the body of the code. I use a fantastic editor,
Source Insight, and can just select the prototype name and jump to the
function, or select the name of a function in a call, and jump to the
prototype or the definition. Makes for easy
navigation
The program I am generating full documentation on, is 15K of binary,
running in a 8051 with 16K of flash. There is no room for C++ overhead,
and the like.
At this level of programming, you want to see each an every line of
code. You also have to abuse coding practices to save memory space at times.
Abusing coding practices, like falling from one case directly into another
in a switch statement, at times can be advantageous and useful, but not
considered good programming
practice.
I will say, that the way doxygen works by using headers, has a major
problem, when the prototypes don't even have an identifier in them,
but the function does, and the body of the function references them. The
way it is now, this just flat falls on it's face, forcing the user to have
to edit the output from
doxygen heavily to fix things like this....
And at the moment, I am the sole programmer, and it is likely to stay that
way until I retire. THEN the documentation has to be good enough that the
guy coming in behind me, can understand and
maintain it.
>
>
>From: woody [mailto:kn...@re...]
>Sent: Friday, September 04, 2015 10:55 AM
>To: Frank Peelo; dox...@li...
>Subject: Re: [Doxygen-users] Another question....
>
>
>
>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:Dox...@li...>Dox...@li...
>
>https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>
>------------------------------------------------------------------------------
>_______________________________________________
>Doxygen-users mailing list
><mailto:Dox...@li...>Dox...@li...
>https://lists.sourceforge.net/lists/listinfo/doxygen-users
>
>------------------------------------------------------------------------------
>_______________________________________________
>Doxygen-users mailing list
>Dox...@li...
>https://lists.sourceforge.net/lists/listinfo/doxygen-users
|
