[Pkg-libburnia-devel] Bug#718151: doxygen loops when passing "foo(>0)" to findParameterList

[Helmut Grohne]

Control: clone 718151 -1
Control: reassign -1 doxygen 1.8.4-1
Control: severity -1 normal
Control: retitle -1 doxygen loops when passing "foo(>0)" to findParameterList

On Sat, Aug 03, 2013 at 11:21:11PM +0200, Matthias Klose wrote:
> fix it in libburn or disable building the docs.  upstream did tell you that they
> didn't want to update that for newer doxygen versions.  There is absolutely no
> reason to reassign this to doxygen.

While the report was not overly helpful, part of the issue is with
doxygen. I looked into the issue and pull in
doxygen-develop at lists.sourceforge.net for further assistance.

So the issue at hand is that doxygen does not terminate when building
the documentation for libburn. On interrupting doxygen after leaving it
running for some time you will see a traceback like this:

#0  findParameterList (name=...) at util.cpp:1848
#1  0x00000000005f894f in resolveRef (scName=0x0, name=0x1657d30 "burn_abort(>0)", inSeeBlock=false, resContext=0x7fff9a4e8c40, resMember=0x7fff9a4e8c48, lookForSpecialization=true, currentFile=0x1603fc0, checkScope=true) at util.cpp:4363
#2  0x00000000006a608c in handleLinkedWord (parent=0x1c8f4c0, children=...) at docparser.cpp:1030
#3  0x00000000006b832e in DocPara::parse (this=0x1c8f480) at docparser.cpp:6311
#4  0x00000000006b257e in DocSimpleSect::parse (this=0x1c8f410, userTitle=false, needsSeparator=false) at docparser.cpp:4570
#5  0x00000000006b3436 in DocPara::handleSimpleSection (this=0x16594c0, t=DocSimpleSect::Since, xmlContext=false) at docparser.cpp:4887
#6  0x00000000006b59bf in DocPara::handleCommand (this=0x16594c0, cmdName=...) at docparser.cpp:5399
#7  0x00000000006b8a4e in DocPara::parse (this=0x16594c0) at docparser.cpp:6478
#8  0x00000000006b9abb in DocRoot::parse (this=0x1651080) at docparser.cpp:6843
#9  0x00000000006ba35b in validatingParseDoc (fileName=0x164f620 ".../libburn/libburn.h", startLine=3608, ctx=0x156b7e0, md=0x183a3a0, input=0x1653f80 " Either by setting an own handler or\nby activating the built-in signal handler.\n\nA function parameter handle of NULL activates the built-in abort handler. \nDepending on mode it may cancel all drive op"..., indexWords=true, isExample=false, exampleName=0x0, singleLine=false, linkFromIndex=false) at docparser.cpp:7085
#10 0x0000000000574224 in OutputList::generateDoc (this=0x18790e0, fileName=0x164f620 ".../libburn/libburn.h", startLine=3608, ctx=0x156b7e0, md=0x183a3a0, docStr=..., indexWords=true, isExample=false, exampleName=0x0, singleLine=false, linkFromIndex=false) at outputlist.cpp:153
#11 0x000000000055e4a0 in MemberDef::writeDocumentation (this=0x183a3a0, ml=0x17405b0, ol=..., scName=0x1641150 "libburn.h", container=0x1603fc0, inGroup=false, showEnumValues=false, showInline=false) at memberdef.cpp:2745
#12 0x000000000056aff5 in MemberList::writeDocumentation (this=0x17405b0, ol=..., scopeName=0x1641150 "libburn.h", container=0x1603fc0, title=0x163d660 "Function Documentation", showEnumValues=false, showInline=false) at memberlist.cpp:655
#13 0x0000000000446904 in FileDef::writeMemberDocumentation (this=0x1603fc0, ol=..., lt=MemberListType_docFuncMembers, title=...) at filedef.cpp:1742
#14 0x000000000044263f in FileDef::writeDocumentation (this=0x1603fc0, ol=...) at filedef.cpp:685
#15 0x000000000042364f in generateFileDocs () at doxygen.cpp:7842
#16 0x0000000000430ab7 in generateOutput () at doxygen.cpp:11231
#17 0x00000000004032c6 in main (argc=2, argv=0x7fff9a4e9818) at main.cpp:38

Indeed the issue lies within findParameterList. The name parameter
passed to resolvRef as a c string is passed to the former function as a
QString, but its value still represents "burn_abort(>0)". Given this
value, findParameterList goes into an infinite "do { ... } while (...)"
loop. The loop iterations alternate between templateDepth=0 and
templateDepth=1. On the second iteration it will take "then" branch of
the outer "if" and will set nextOpenPos=-1 and nextClosePos=-1. This
causes the inner "else" branch to be selected setting pos=-2 and thus
continuing the loop.

A possible fix would be to change the loop condition from
"while(pos != -1)" to "while(pos >= 0)".

Is this analysis correct?

As for the libburn maintainers, I suggest to change the comment in the
header to not include the verbatim string "burn_abort(>0)" in order to
not confuse doxygen. Yeah, it's a bug in doxygen that it loops, but
you'll have to work around this one for the time being.

Helmut