GNOME Bugzilla – Bug 650880
VHDL: elements and their description are mixed in the RTF output
Last modified: 2018-07-30 10:22:10 UTC
I generated a documentation from my VHDL sources in both HTML and RTF formats. All is correctly sorted in the HTML output wheras in the generated RTF the lists of processes, signals and component instanciations set the comments at the beginning of the next item in the list. For instance the code extract: " signal clk : std_logic; --! main clock signal rst_n : std_logic; --! main asynchronous reset active low signal rst : std_logic; --! main asynchronous reset active high " Gives the following wrong list in the RTF generated: " Signals • clk std_logic • main clock rst_n std_logic • main asynchronous reset active low rst std_logic • main asynchronous reset active high next_frame_s std_logic " Whereas the HTML page correctly lists: " Signals clk std_logic main clock rst_n std_logic main asynchronous reset active low rst std_logic main asynchronous reset active high "
I took a look at the Doxygen's code and if I am not wrong the following lines must be added at the end of the VhdlDocGen::writeVHDLDeclaration function: ol.pushGeneratorState(); ol.disableAllBut(OutputGenerator::RTF); ol.startParagraph(); ol.endParagraph(); ol.popGeneratorState(); before ol.endMemberDescription(); Indeed for other languages, the function used is MemberDef::writeDeclaration and this function ends like that: // write brief description if (!briefDescription().isEmpty() && Config_getBool("BRIEF_MEMBER_DESC") /* && !annMemb */ ) { ol.startMemberDescription(); ol.parseDoc(briefFile(),briefLine(), getOuterScope()?getOuterScope():d,this,briefDescription(), TRUE,FALSE,0,TRUE,FALSE); if (detailsVisible) { ol.pushGeneratorState(); ol.disableAllBut(OutputGenerator::Html); //ol.endEmphasis(); ol.docify(" "); if (m_impl->group!=0 && gd==0) // forward link to the group { ol.startTextLink(getOutputFileBase(),anchor()); } else // local link { ol.startTextLink(0,anchor()); } ol.endTextLink(); //ol.startEmphasis(); ol.popGeneratorState(); } <b>// for RTF we need to add an extra empty paragraph ol.pushGeneratorState(); ol.disableAllBut(OutputGenerator::RTF); ol.startParagraph(); ol.endParagraph(); ol.popGeneratorState();</b> ol.endMemberDescription(); } warnIfUndocumented(); } If I understand well MemberDef::writeDeclaration and VhdlDocGen::writeVHDLDeclaration do the same job and these parts of the code should be the same... And if someone can explain me why the "newparagraph" in endMemberDescription is not sufficient to have a "\par" in the RTF output after the member detailed description, I would be very grateful.
I finally was able to check the modification listed here above. It seems good but it corrects only a part of my problem. Moreover, a simple line break seems to work fine. Adding ol.pushGeneratorState(); ol.disableAllBut(OutputGenerator::RTF); ol.lineBreak(); ol.popGeneratorState(); before ol.endMemberDescription(); at the end of the VhdlDocGen::writeVHDLDeclaration function corrects the line return for port lists, but I still have a bad display for: * Lists of architectures in the class description of each entity * Lists of "architectures" (in fact classes) in the file descriptions. After further investigation it seems that adding ol.pushGeneratorState(); ol.disableAllBut(OutputGenerator::RTF); ol.lineBreak(); ol.popGeneratorState(); at the very beginning of the VhdlDocGen::writeVhdlDeclarations function corrects the line return for the list of architectures in the Entity Reference section. I am still looking for where to apply the correction to solve the last problem (list of architectures in file descriptions).
Note: I checked the two changes above with the Release_1.7.4_20110727 tag version of the sources. This is the most recent version which I can compile in my environment, more recent versions lead to errors in some files which manage the tcl language.
Created attachment 194703 [details] [review] Proposed patch to correct line breaks missing in VHDL RTF output I was wrong for the second modification. The following change solves both problems in "architectures" lists. In classdef.cpp, add ol.pushGeneratorState(); ol.disableAllBut(OutputGenerator::RTF); ol.lineBreak(); ol.popGeneratorState(); before ol.endMemberDescription(); at the end of the ClassDef::writeDeclarationLink function. Checked on tag 1.7.4_20110727 with my VHDL project: the result is as I desired. Here is the corresponding patch.
Bug confirmed in versions 1.7.5.1 and 1.8.2. Proposed fix confirmed in version 1.7.5.1.
As discussed in https://github.com/doxygen/doxygen/pull/734 , Doxygen has moved its issue tracking to https://github.com/doxygen/doxygen/issues All Doxygen tickets in GNOME Bugzilla have been migrated to Github. You can subscribe and participate in the new ticket in Github. You can find the corresponding Github ticket by searching for its Bugzilla ID (number) in Github. Hence I am closing this GNOME Bugzilla ticket. Please use the corresponding ticket in Github instead. Thanks a lot!