GNOME Bugzilla – Bug 622041
malformed/malfunctioning attribute documentation parsing
Last modified: 2012-11-18 11:12:34 UTC
Created attachment 164050 [details] the two header files + the generated HTML documentation + Doxyfile I'm trying to completely separate my documentation definitions from my code with the help of doxygen's "special commands" (like \class, \namespace, \var, etc.) It works all well for namespaces, classes, etc. but there seems to be a bug in the parsing code for attribute documentation. For instance I've got two header files: -> class.h (http://www.fuse-software.com/doxy_test/class.h.txt) namespace Namespace { class Class { public: int mAttribute1; int mAttribute2; int mAttribute3; }; } -> doc.h (http://www.fuse-software.com/doxy_test/doc.h.txt) /** \namespace Namespace \details the namespace documentation \class Namespace::Class \details the class documentation \var int Namespace::Class::mAttribute1 \details the 1st attribute's documentation \var int Namespace::Class::mAttribute2 \details the 2nd attribute's documentation \var int Namespace::Class::mAttribute3 \details the 3rd attribute's documentation */ As said for the namespaces and classes this works perfectly fine, but the attribute documentation doesn't work as it should. This is what the generated documentation looks like for the above files: http://www.fuse-software.com/doxy_test/html/class_namespace_1_1_class.html As you can clearly see, the documentation of the three attributes is being concatenated together and assigned to the very last attribute (also some strange attribute name concatenation takes place). My guess would be a fault in the code that parses the attribute documentation.
I've debugged the bug a little bit and found something suspicious. at "commentscan.l" arround line 460: static bool makeStructuralIndicator(Entry::Sections s) { if (!getDocSectionName(current->section).isEmpty()) { return TRUE; } else { needNewEntry = TRUE; <---- the needNewEntry is never used anywhere current->section = s; current->fileName = yyFileName; current->startLine = yyLineNr; return FALSE; } } The value of the marked "needNewEntry" variable is never actually used, this might be part of the problem. In result the "current" Entry stays the same for all of the four attributes from the above example and therefore the names and documentations of all four attributes are appended to the very same Entry. That's about as far as I was able to track the problem down without knowing details about neither the doxygen source code nor flex/bison. Cheers
Hi Wolfgang, I can confirm the problem. Your suggestion that needNewEntry is not used is not true however. It is used around line 2548 of commentscan.l. But you were close. I think the real issue is that after the first variable current->section is equal to VARIABLEDOC_SEC, but case is not handled in getDocSectionName. So this patch should fix it: diff -u ../../doxygen-svn/src/commentscan.l commentscan.l --- ../../doxygen-svn/src/commentscan.l 2010-06-15 12:21:19.000000000 +0200 +++ commentscan.l 2010-06-19 09:46:39.000000000 +0200 @@ -433,6 +433,7 @@ case Entry::CATEGORYDOC_SEC: return "\\category"; case Entry::ENUMDOC_SEC: return "\\enum"; case Entry::PAGEDOC_SEC: return "\\page"; + case Entry::VARIABLEDOC_SEC: return "\\var"; case Entry::MEMBERDOC_SEC: return "\\fn"; case Entry::OVERLOADDOC_SEC: return "\\overload"; case Entry::FILEDOC_SEC: return "\\file";
Hi Dimitri, Thanks for the quick reply/fix, I'm glad that it was such an easy one. I tried to do my best to narrow the problem down as far as I could, but I only ever used JavaCC once and never crossed paths with Bison/Flex yet :) Again, thanks for the quick reply, I patched the latest SVN version of the code and now it works perfectly fine. Regards, Wolfgang
This bug was previously marked ASSIGNED, which means it should be fixed in doxygen version 1.7.1. Please verify if this is indeed the case. Reopen the bug if you think it is not fixed and please include any additional information that you think can be relevant.
This bug was previously marked ASSIGNED, which means it should be fixed in doxygen version 1.7.2. Please verify if this is indeed the case. Reopen the bug if you think it is not fixed and please include any additional information that you think can be relevant.