New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

malformed/malfunctioning attribute documentation parsing (Origin: bugzilla #622041) #3814

Closed
doxygen opened this Issue Jul 2, 2018 · 0 comments

Comments

Projects
None yet
1 participant
@doxygen
Owner

doxygen commented Jul 2, 2018

status RESOLVED severity major in component documentation for ---
Reported in version unspecified on platform Other
Assigned to: Dimitri van Heesch

Original attachment names and IDs:

On 2010-06-18 23:51:00 +0000, Wolfgang Steiner wrote:

Created attachment 164050
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.

On 2010-06-19 04:02:30 +0000, Wolfgang Steiner wrote:

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

On 2010-06-19 07:51:33 +0000, Dimitri van Heesch wrote:

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";

On 2010-06-19 16:09:35 +0000, Wolfgang Steiner wrote:

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

On 2010-06-25 11:49:00 +0000, Dimitri van Heesch wrote:

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.

On 2010-10-09 08:19:42 +0000, Dimitri van Heesch wrote:

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.

@doxygen doxygen closed this Jul 2, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment