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, <franz.holle...@emerson.com> 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: albert.v.d.m...@gmail.com [mailto:albert.v.d.m...@gmail.com] On >> Behalf Of Albert >> Sent: Donnerstag, 21. Februar 2013 20:04 >> To: Hollerer, Franz [NETPWR/EMBPW/AT] >> Cc: doxygen-users@lists.sourceforge.net >> 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, <franz.holle...@emerson.com> 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: albert.v.d.m...@gmail.com [mailto:albert.v.d.m...@gmail.com] >> On >> >> Behalf Of Albert >> >> Sent: Donnerstag, 21. Februar 2013 18:40 >> >> To: Hollerer, Franz [NETPWR/EMBPW/AT] >> >> Cc: doxygen-users@lists.sourceforge.net >> >> 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, <franz.holle...@emerson.com> >> 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 >> >> > Doxygen-users@lists.sourceforge.net >> >> > https://lists.sourceforge.net/lists/listinfo/doxygen-users ------------------------------------------------------------------------------ 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 Doxygen-users@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/doxygen-users
