GNOME Bugzilla – Bug 662190
Related pages todo, bug etc. show up with only one item per class
Last modified: 2011-12-03 18:22:51 UTC
Using the new TCL scanner I created a file containing tcl code. In addition the doxy config file contains ALIASES += "req=\xrefitem requirement \"Requirement\" \"Requirements List\" " The Related Page for Bugs, Todos and Req contain only one element per class i.e. the bug bug123 and bug2 is missing, same with the other related pages. ## @file tclass.itcl # @brief hello tom ## @author Jon Do, Od Noj # @copyright Siemens AG Oesterreich # @brief Something about the basic-test class # @bug bug1 hello1 # @todo do sowmthing new here 1 itcl::class basic-test { inherit parentclass1 parentclass2 constructor {} public method test1 {} ;#< brief description of method test1 public variable mybasicvar1 1 ;#< description of variable1 public variable mybasicvar2 2 ;#< description of variable2 #private variable myprivate 2 } ## @author Jon Do, Od Noj # @brief give me a note about the body # @returns not really specials # @param par1 tell you something about par1 # @param par2 tell you something about par2 # @details More details on this proc # can be entered later # @bug bug2 hello2 # @todo do sowmthing new here 2 # @req HTR-3 first requirement itcl::body basic-test::test1 {par1 par2 args} { ##ProcedureRange ##ProcedureArgs set options(a) 1 ##EndArgs } ## desc of parentclass1 # @bug bug456 hello3 # @req HTR-4 was from customer xzqqqy itcl::class parentclass1 { public method m1 {} } ## hi tom # @bug bug123 hello5 # @req HTR-6 was from customer 124 itcl::body parentclass1::m1 {} {} ## desc of parentclass2 itcl::class parentclass2 { public method m2 {} }
Multiple @bug and @todo statements work only in class comments. Statements in function comments are documented in the function description but not in the TODO and BUG page. A question for Dimitri: In tclscanner.l I use the convertCppComments() function to resolv ALIASES and the parseCommentBlock() function to parse the comments. Is there something special before calling these functions. Should I have to set something additional in the entry?
I had an older implementation of the tclscanner using doxygen 1.7.4 (not from you and not so sophisticated) in which each @bug showed up in the related page no matter where I put it. The point is - bug2 shows up in the method description - so principally it's working - only it doesn't show up in the related pages ... whatever reason ... thx for your support!
The statements are only missing if the documentation is done before the itcl::body part. If the documentation is done before the method declaration inside the class declaration it is working. To fix it I have to understand the the comment parsing. May be Dimitri can give me a hint: How can I add parsed documentation from one entry to another entry? Currently I only add the entry->brief and entry->doc part.
Created attachment 200716 [details] tcl scanner implementation
Workaround is to create separate entries for declaration and definition. Some other changes in the new tclscanner.l file: - Create links for commands inside [] - No creation of namespaces for classes without common procedures - Overall use of 0x1A to delimit scan context - Support of TCL_SUBST aliases in Doxyfile. To use this you have to insert the following lines in files config.xml: <option type='list' id='TCL_SUBST' format='string' docs=' This tag can be used to specify a number of word-keyword mappings. An mapping has the form "name=value". For example adding "class=itcl::class" will allow you to use the command class in the itcl::class meaning. '> </option>
Hi Rene, I'll include your patch in the next subversion update. I'm still not sure from the description how a user would use TCL_SUBST. Can you give a small example? As for convertCppComments(): that should ideally be called on the whole file as it also does @cond processing, which can span multiple comments.
In tcl doesn't exist a single object system. You can even use different systems in your code. To use it you can use fully qualified commands like 'itcl::class' or 'oo::class'. But you can also import the commands and simply use 'class'. The import doesn't have to be in the same file. Also tcl is highly dynamic. You could write your own object system in it. Or you can use your own special command to create functions. With TCL_SUBST settings the doxygen parser can understand the used syntax and use the correct parsing to create the documentation. Do you mean calling convertCppComments() like in doxygen.cpp? Unfortunately we have in tcl other comments (using #). Is the @cond processing the only reason to call it on the whole file? I will have a look on the @cond part.
(In reply to comment #7) > > With TCL_SUBST settings the doxygen parser can understand the used syntax > and use the correct parsing to create the documentation. But are the substitutions done on all tokens in the source file, or just within comment blocks, or only when the parser expects a function or a type? > > Do you mean calling convertCppComments() like in doxygen.cpp? > Unfortunately we have in tcl other comments (using #). > Is the @cond processing the only reason to call it on the whole file? > I will have a look on the @cond part. I think the best solution would be to split the scanner into a language specific part that just looks for comment blocks, and a language neutral part that does the alias and @cond processing. The language specific parser could be triggered by a new method in the abstract ParserInterface.
Substitutions are done on all commands outside of comments. You can find it inside tcl_command(): // remove leading "::" and apply TCL_SUBST if (myStr.left(2)=="::") myStr = myStr.mid(2); if (tcl.config_subst.contains(myStr)) { myStr=tcl.config_subst[myStr]; } The substituted string is then used so p.e. TCL_SUBST = function=proc PRIV=private gives the same result for the following two lines: PRIV function myfunc {} {} private proc myfunc {} {} Mmh, the language neutral part for comments would be fine. May be give it the comment part without the surrounding delimeters (in C /* and */, C++ // and shells #). Currently I already strip the # and add /* and */. But I would prefer only one parser for one language. Have you p.e. considered how to work with comments after declarations and separate parsers?
This bug was previously marked ASSIGNED, which means it should be fixed in doxygen version 1.7.6. 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.