Re: [Doxygen-users] Warning "@param is not found in the argument list of" when documenting global variable as function parameter

[Albert <alb...@gm...>]

Dear Franz,

I agree with you. Can you file a bug / enhancement request for this in bugzilla?

Regarding:
>  I will change it if it is not the way the doxygen team has in mind.
Everybody can of course choose how to use Doxygen and it may take a
while before a command like \global is available.

Albert


On Fri, Feb 22, 2013 at 9:24 AM,  <Fra...@em...> wrote:
> Dear Albert,
>
> I would appreciate a \global command which works similar to the \param, even with the [in], [out] and [in,out] decorator. This would give me a good method to document the use of globals.
>
> I would prefer this method over the automatic generated list, because it gives me better control on what I want to draw the reader's attention to.
>
> The problem is that I did not find a hint on how to document the use of a global variable in context of a function within the doxygen manual. Thus I found an apparently working solution by trial and error. I will change it if it is not the way the doxygen team has in mind.
>
> Well globals are bad, and I try to avoid them where possible. If inevitable, I try to limit the visibility to module scope - as I did with the "static uint8_t crc_table[]" example. Maybe this is a point which would make sense to distinguish in the generated documentation too: global versus module global?
>
> Thanks & Best regards,
>
> Franz Hollerer
>
>
>> -----Original Message-----
>> From: alb...@gm... [mailto:alb...@gm...] On
>> Behalf Of Albert
>> Sent: Donnerstag, 21. Februar 2013 20:04
>> To: Hollerer, Franz [NETPWR/EMBPW/AT]
>> Cc: dox...@li...
>> Subject: Re: [Doxygen-users] Warning "@param is not found in the
>> argument list of" when documenting global variable as function
>> parameter
>>
>> Dear Franz,
>>
>> Well this is another interpretation than I have, but I don't want to
>> start a discussion about this.
>> I can imagine that for your purpose this might work, but I think that
>> when using e.g. the USE statement in Fortran just the global namespace
>> does not give enough information, here one should have the module name
>> with it as well and I think that in C++ etc. similar considerations
>> might be in place.
>>
>> Albert
>>
>> On Thu, Feb 21, 2013 at 6:55 PM,  <Fra...@em...> wrote:
>> > Dear Albert,
>> >
>> > well my idea of a global variable in the context of a function is
>> that it is just a [in], [out] or [in,out] parameter to that function
>> even if it is not listed in the parameter list. The "::" prefix tells
>> that it is in the global namespace.
>> >
>> > The doxygen output is fine. Doxygen does exactly produce what I want.
>> Even the [in/out/in,out] stuff is there.
>> >
>> > The one and only think I dislike is the warning...
>> >
>> > Franz
>> >
>> >> -----Original Message-----
>> >> From: alb...@gm... [mailto:alb...@gm...]
>> On
>> >> Behalf Of Albert
>> >> Sent: Donnerstag, 21. Februar 2013 18:40
>> >> To: Hollerer, Franz [NETPWR/EMBPW/AT]
>> >> Cc: dox...@li...
>> >> Subject: Re: [Doxygen-users] Warning "@param is not found in the
>> >> argument list of" when documenting global variable as function
>> >> parameter
>> >>
>> >> Dear Franz,
>> >>
>> >> The thought behind the question is quite intriguing, I've been
>> >> thinking about how to make it clear that a routine uses global
>> >> variables. I don't think one should miss use the @param for this as
>> >> @param is meant for  parameters/ arguments of the routine.
>> >> I don't think functionality you would like to have exists.
>> >>
>> >> One solution would be that the user can specify by means of a
>> >> statement similar to the @param statement (e.g. @global) the
>> >> variables that are used by the routine and these variables would be
>> >> listed in a separate section and could be liked to the definition of
>> >> the variables. This is of course error prone as the developer has to
>> maintain the list.
>> >> Another possibility would be to have Doxygen parse the routine and
>> >> see which variables are not arguments or local variables and create
>> a
>> >> list of these. This method also has some disadvantages, a.o. when a
>> >> user includes a files with some standard definitions for variables
>> >> (unfortunately this exists) or in languages like Fortran where it is
>> >> not mandatory to declare all variables let alone languages like
>> Python.
>> >>
>> >> Just some of my thoughts
>> >>
>> >> Albert
>> >>
>> >> On Thu, Feb 21, 2013 at 4:22 PM,  <Fra...@em...>
>> wrote:
>> >> > Hi,
>> >> >
>> >> > I use the \param together with "::" to document the use of global
>> >> variables within a function. This works fine, but I get a warning
>> >> about "@param is not found in the argument list...". Can I turn off
>> >> the warning for the case the parameter is not in the functions
>> >> parameter list, but is a global variable?
>> >> >
>> >> > Example:
>> >> >
>> >> > /**
>> >> >  * Lookup table for CRC calculation.
>> >> >  */
>> >> > static uint8_t crc_table[] = {
>> >> > ...
>> >> > };
>> >> >
>> >> > /**
>> >> >  * Calculates CRC.
>> >> >  *
>> >> >  * \param[in] data Points to data for which to calculate the CRC.
>> >> >  * \param[in] len  Number of bytes.
>> >> >  * \param[in] ::crc_table
>> >> >  */
>> >> > uint16_t CalcCRC(uint8_t *data, size_t len) {
>> >> >     ...
>> >> > }
>> >> >
>> >> > Doxygen does exactly what I want. The global variable crc_table is
>> >> listed as input parameter within the documentation for the CalcCRC()
>> >> function and it also gives a link to the global variable itself.
>> >> >
>> >> > That's pretty fine. The only unpleasant fact is the warning
>> itself.
>> >> Is there a way to prevent this warning without turning it off
>> >> generally?
>> >> >
>> >> > BTW: I use doxygen 1.7.4.
>> >> >
>> >> > Thanks & Best regards,
>> >> >
>> >> > Franz Hollerer
>> >> >
>> >> >
>> >> > ------------------------------------------------------------------
>> -
>> >> > --
>> >> -
>> >> > -------- Everyone hates slow websites. So do we.
>> >> > Make your web apps faster with AppDynamics Download AppDynamics
>> >> > Lite for free today:
>> >> > http://p.sf.net/sfu/appdyn_d2d_feb
>> >> > _______________________________________________
>> >> > Doxygen-users mailing list
>> >> > Dox...@li...
>> >> > https://lists.sourceforge.net/lists/listinfo/doxygen-users