GNOME Bugzilla – Bug 796110
@param for template param doesn't work when name starts from underscore
Last modified: 2018-07-30 10:16:08 UTC
The curiosity I found while testing fix for bug 796094. I noticed it while testing this very version ( https://github.com/doxygen/doxygen/pull/724 ), not sure when it appeared but 1.8.13 doesn't have this problem. Synopsis ============= In case someone writes @param instead of @tparam for template parameter, doxygen (in aforementioned version) usually detects what's going on and silently fixes the issue … but not when the template parameter starts with underscore. In such case I get confusing warning: bis.hxx:5: warning: unexpected token in comment block while parsing the argument of command param (I get this for ThisFails below, while both ThisWorks and ThisWorksToo work properly) Example code =============== /** Some class @param _R Some type **/ template<typename _R> class ThisFails; /** Some class @param R Some type **/ template<typename R> class ThisWorks; /** Some class @tparam _R Some type **/ template<typename _R> class ThisWorksToo;
Non-pr tip (df0d9c3d) also have this problem.
1.8.14 is OK (doesn't have the problem). So it's something fresh. I tried bisect-ing but naive bisect goes confused among those numerous branches. But roughly it seems that it's one of the changes merged at 2018-04-22. The whole problem, as such, is not very important (after all changing @param to more proper @tparam fixes the issue), but I'd really prefer "warning: please use @tparam instead of @param for templates" to "warning: unexpected token" ;-)
Difficult problem as it has to do with the order of processing in respect to Markdown. The current problems here have been introduced by the changes for the issue: bug_792122 - XHTML pages are broken several ways (pull request 674 on github). Also related to this issue is bug: bug_775493 - Usage of underscore's in parameter names Note: also that in version 1.8.14 there exist problems with the tparam command in case the names starts and ends with single or double underscores. I think that in general all commands where the name of a variables is used and the name of the variable name starts and ends with single or double underscores gives problems.
I understand, that the problem happens because parser treats _ as „start italic” marker. But IIUC, parameter names doesn't support formatting… And why @param and @tparam behave differently?
Indeed parameter names do not support formatting. But due to the place of the handling of the markdown support this is now happening. That @param and @tparam behave differently is due to the fact that they (incorrectly?) go through a different part of the code. Outside the Bugzilla discussion looking for a solution.
As discussed in https://github.com/doxygen/doxygen/pull/734 , Doxygen has moved its issue tracking to https://github.com/doxygen/doxygen/issues All Doxygen tickets in GNOME Bugzilla have been migrated to Github. You can subscribe and participate in the new ticket in Github. You can find the corresponding Github ticket by searching for its Bugzilla ID (number) in Github. Hence I am closing this GNOME Bugzilla ticket. Please use the corresponding ticket in Github instead. Thanks a lot!