Please be aware: doxygen: confusion about \ref and \a

Researching for a discussion at https://gerrit.osmocom.org/c/libosmocore/+/12384 made me realize that our use of doxygen keywords is currently confused. TLDR: - Links to structs, members and functions are implicit in doxygen. - Don't use '\ref', except to link to sections or files. - Don't use '\a', it is merely cosmetic and breaks reading flow for some. Details: (*) We are often using '\ref' wrongly, and also '\a' is merely cosmetic. Example: osmo_crc16(), see param 'len' intending to reference the 'buffer' param: /*! Compute 16bit CCITT polynome 0x8408 (x^0 + x^5 + x^12) over given buffer. * \param crc[in] previous CRC value * \param buffer[in] data pointer * \param len[in] number of bytes in input \ref buffer * \return updated CRC value */ uint16_t osmo_crc16(uint16_t crc, uint8_t const *buffer, size_t len) ... It looks perfectly sane, but this is wrong for more than one reason: - '\ref' is not actually about code elements. It is about referencing pages or code sections. See http://www.doxygen.nl/manual/commands.html#cmdref "Creates a reference to a named section, subsection, page or anchor." Doxygen complains with e.g.: "gsmtap_util.c:192: warning: unable to resolve reference to `data' for \ref command" Luckily '\ref' doesn't break implicit linking, which is probably why the misconception that we need to include them arose in the first place. - There *AREN'T* any references to function arguments at all!! It is not possible in doxygen to create a formal link to a function argument. You can reference struct members, functions, ... but not arguments. API code often uses '\a' (at least 320 times in libosmocore), but that does not add a formal link, either. '\a' is only and simply putting a term in italics. http://www.doxygen.nl/manual/commands.html#cmda There are currently at least 260 uses of '\ref' in libosmocore, of which only a few are correct. An example of correct use is gsmtap_source_init(): http://ftp.osmocom.org/api/latest/libosmocore/core/html/group__gsmtap.html#… /*! [...] integrated with libosmocore \ref select */ which renders as integrated with libosmocore [Select loop abstraction] Ironically, the same gsmtap_source_init() also includes examples of incorrect use, ignore those for this argument, please. (*) Hyperlinks are fully automatic and implicit. Notice that formal links are detected automatically, without the need for an explicit doxygen marker. For example, look at the API doc for osmo_cgi_name2(): http://ftp.osmocom.org/api/latest/libosmocore/gsm/html/gsm23003_8c.html#af9… It has a link to osmo_cgi_name(), with a doxygen source of /*! Same as osmo_cgi_name(), but uses a different static buffer. [...] I will hence continue to omit '\a' and '\ref', and will actually ask patch submitters to omit them in code review. ~N