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

[George Danchev]

On Sunday 04 August 2013 14:31:06 Helmut Grohne wrote:
> 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 

Matthias,
The fix should be in doxygen proper, since it should not just hang when faced 
with "odd" input! Workaround is another thing, but then again, chances are 
very high that multiple packages are affected by this doxygen FAIL, so it is 
not only libburn when a workaround is possibly be needed.

> > or disable building the docs.  
I won't even comment that.

> > upstream did tell 
> > you that they didn't want to update that for newer doxygen versions.  

Sorry, but this is all plain wrong. Thomas did not tell such things, we are 
well in touch, and I also have write access to the upstream repo, so the above 
statement is sure void.

> > There is absolutely no reason to reassign this to doxygen.

I'd rather have that with doxygen on time, before more packages figure out that 
they are also affected by this doxygen 1.8.4 FAIL.

> 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.

Helmut,
Thanks for your understanding. I disagree a bit with the "report was not 
overly helpful" because I provided the affected version of doxygen, the version 
of the libburn (resp. the public header) which provokes this FAIL in doxygen, 
and I also mentioned that the FAIL is reliably reproducible (Sorry, I'm in 
VAC, properly documented, so I can not go further into tracking doxygen 
entrails). I also disagree with the statement that "part of the issue is with 
doxygen"... the whole FAIL is with doxygen, because however awkward the header 
is, doxygen should not get stuck, even in a endless loop.

> 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.

Thanks. The stuck is no longer reproducible with the applied workaround by 
Thomas. But do in mind that libburn most probably is not alone, which needs to 
apply a workaround.

-- 
pub 4096R/0E4BD0AB <people.fccf.net/danchev/key pgp.mit.edu>