From 1a403d80160458091bab7c442e54f836c0b90bca Mon Sep 17 00:00:00 2001 From: zmhuang Date: Mon, 8 Dec 2014 19:19:32 +0800 Subject: fix docbook output 1. support other than english 2. fix broken example link id 3. fix incomplete TOC : no Classe etc. 4. add brief description for Functions etc. 5. Comply with REPEAT_BRIEF 6. Do not output duplicated contents when detailed descripton is missing. 7. set table colwidth for Param/RetVal --- src/docbookgen.cpp | 241 ++++++++++++++++++++++++++++--------------------- src/docbookvisitor.cpp | 2 + 2 files changed, 139 insertions(+), 104 deletions(-) diff --git a/src/docbookgen.cpp b/src/docbookgen.cpp index 990224e..edcafdb 100644 --- a/src/docbookgen.cpp +++ b/src/docbookgen.cpp @@ -484,6 +484,12 @@ static void generateDocbookForMember(MemberDef *md,FTextStream &t,Definition *de } t << endl << "}"; t << "" << endl; + if (md->briefDescription()) + { + t << ""; + writeDocbookString(t,md->briefDescription()); + t << "" << endl; + } } } else if (md->memberType()==MemberType_Define) @@ -536,6 +542,12 @@ static void generateDocbookForMember(MemberDef *md,FTextStream &t,Definition *de t << memberOutputFileBase(md); } t << "_1" << md->anchor() << "\">" << convertToXML(md->name()) << ""; + if (md->briefDescription()) + { + t << ""; + writeDocbookString(t,md->briefDescription()); + t << "" << endl; + } } } else if (md->memberType()==MemberType_Typedef) @@ -554,6 +566,12 @@ static void generateDocbookForMember(MemberDef *md,FTextStream &t,Definition *de t << memberOutputFileBase(md); } t << "_1" << md->anchor() << "\">" << convertToXML(md->name()) << ""; + if (md->briefDescription()) + { + t << ""; + writeDocbookString(t,md->briefDescription()); + t << "" << endl; + } } else if (md->memberType()==MemberType_Function) { @@ -597,6 +615,12 @@ static void generateDocbookForMember(MemberDef *md,FTextStream &t,Definition *de } } t << ")"; + if (md->briefDescription()) + { + t << ""; + writeDocbookString(t,md->briefDescription()); + t << "" << endl; + } } else { @@ -631,7 +655,7 @@ static void generateDocbookForMember(MemberDef *md,FTextStream &t,Definition *de MemberListIterator emli(*enumFields); MemberDef *emd; t << " " << endl; - t << " Enumerator:" << endl; + t << " " << theTranslator->trEnumerationValues() << ":" << endl; t << " " << endl; for (emli.toFirst();(emd=emli.current());++emli) { @@ -641,9 +665,12 @@ static void generateDocbookForMember(MemberDef *md,FTextStream &t,Definition *de writeDocbookString(t,emd->name()); t << "" << endl; t << " " << endl; - t << " "; - writeDocbookString(t,emd->briefDescription()); - t << "" << endl; + if(Config_getBool("REPEAT_BRIEF")) + { + t << " "; + writeDocbookString(t,emd->briefDescription()); + t << "" << endl; + } t << " " << endl; t << " " << endl; } @@ -681,9 +708,12 @@ static void generateDocbookForMember(MemberDef *md,FTextStream &t,Definition *de } t << "_1" << md->anchor() << "\">" << endl; t << " " << convertToXML(md->definition()) << ""; - t << " "; - writeDocbookString(t,md->briefDescription()); - t << "" << endl; + if(Config_getBool("REPEAT_BRIEF")) + { + t << " "; + writeDocbookString(t,md->briefDescription()); + t << "" << endl; + } t << " "; writeDocbookDocBlock(t,md->docFile(),md->docLine(),md->getOuterScope(),md,md->documentation()); t << endl; @@ -702,9 +732,12 @@ static void generateDocbookForMember(MemberDef *md,FTextStream &t,Definition *de } t << "_1" << md->anchor() << "\">" << endl; t << " " << convertToXML(md->definition()) << " " << convertToXML(md->argsString()) << ""; - t << " "; - writeDocbookString(t,md->briefDescription()); - t << "" << endl; + if(Config_getBool("REPEAT_BRIEF")) + { + t << " "; + writeDocbookString(t,md->briefDescription()); + t << "" << endl; + } t << " "; writeDocbookDocBlock(t,md->docFile(),md->docLine(),md->getOuterScope(),md,md->documentation()); t << endl; @@ -764,9 +797,12 @@ static void generateDocbookForMember(MemberDef *md,FTextStream &t,Definition *de } t << "_1" << md->anchor() << "\">" << endl; t << " " << convertToXML(md->definition()) << ""; - t << " "; - writeDocbookString(t,md->briefDescription()); - t << "" << endl; + if(Config_getBool("REPEAT_BRIEF")) + { + t << " "; + writeDocbookString(t,md->briefDescription()); + t << "" << endl; + } t << " "; writeDocbookDocBlock(t,md->docFile(),md->docLine(),md->getOuterScope(),md,md->documentation()); t << endl; @@ -796,59 +832,47 @@ static void generateDocbookSection(Definition *d,FTextStream &t,MemberList *ml,c count++; } } + + if (count==0) return; // empty list switch (ml->listType()) { - case MemberListType_decDefineMembers: title="Defines"; desctitle="Define Documentation"; break; - case MemberListType_decTypedefMembers: title="Typedefs"; desctitle="Typedef Documentation"; break; - case MemberListType_decEnumMembers: title="Enumerations"; desctitle="Enumeration Type documentation"; break; - case MemberListType_decFuncMembers: title="Functions"; desctitle="Function Documentation"; break; - case MemberListType_decVarMembers: title="Variables"; desctitle="Variable Documentation"; break; - case MemberListType_pubAttribs: title="Public Attributes"; desctitle="Member Documentation"; break; - case MemberListType_priAttribs: title="Private Attributes"; desctitle="Member Documentation"; break; - case MemberListType_proAttribs: title="Protected Attributes";desctitle="Member Documentation"; break; + case MemberListType_decDefineMembers: title=theTranslator->trDefines(); desctitle=theTranslator->trDefineDocumentation(); break; + case MemberListType_decTypedefMembers: title=theTranslator->trTypedefs(); desctitle=theTranslator->trTypedefDocumentation(); break; + case MemberListType_decEnumMembers: title=theTranslator->trEnumerations(); desctitle=theTranslator->trEnumerationTypeDocumentation(); break; + case MemberListType_decFuncMembers: title=theTranslator->trFunctions(); desctitle=theTranslator->trFunctionDocumentation(); break; + case MemberListType_decVarMembers: title=theTranslator->trVariables(); desctitle=theTranslator->trVariableDocumentation(); break; + case MemberListType_pubAttribs: title=theTranslator->trPublicAttribs(); desctitle=theTranslator->trMemberDataDocumentation(); break; + case MemberListType_priAttribs: title=theTranslator->trPrivateAttribs(); desctitle=theTranslator->trMemberDataDocumentation(); break; + case MemberListType_proAttribs: title=theTranslator->trProtectedAttribs(); desctitle=theTranslator->trMemberDataDocumentation(); break; default: title=""; desctitle=""; break; } - if (count==0) return; // empty list - - for (mli.toFirst();(md=mli.current());++mli) - { - if (md->documentation()) - { - doc_count++; - } - } - if (detailed) { - if (desctitle) + for (mli.toFirst();(md=mli.current());++mli) { - if (desctitle=="Member Documentation") - { - if (doc_count > 0) - { - t << " " << endl; - t << " " << desctitle << "" << endl; - } - } - else if (desctitle=="Define Documentation") - { - if (doc_count > 0) + if (md->documentation().isEmpty() && !Config_getBool("REPEAT_BRIEF")) { - t << "
" << endl; - t << " " << desctitle << "" << endl; + continue; } - } - else - { + doc_count = 1; + break; + } + + if(doc_count == 0) + { + return; + } + + if (desctitle) + { t << "
" << endl; t << " " << desctitle << "" << endl; - } } } else { - t << " " << endl; + t << "
" << endl; if (header) { t << " " << convertToXML(header) << "" << endl; @@ -871,36 +895,24 @@ static void generateDocbookSection(Definition *d,FTextStream &t,MemberList *ml,c // to prevent this duplication in the Docbook output, we filter those here. if (d->definitionType()!=Definition::TypeFile || md->getNamespaceDef()==0) { - generateDocbookForMember(md,t,d,detailed); + if (detailed && md->documentation().isEmpty() && !Config_getBool("REPEAT_BRIEF")) + { + continue; + } + + generateDocbookForMember(md,t,d,detailed); } } if (detailed) { if (desctitle) { - if (desctitle=="Member Documentation") - { - if (doc_count > 0) - { - t << " " << endl; - } - } - else if (desctitle=="Define Documentation") - { - if (doc_count > 0) - { - t << "
" << endl; - } - } - else - { t << "
" << endl; - } } } else { - t << " " << endl; + t << "
" << endl; } } @@ -910,11 +922,11 @@ static void writeInnerClasses(const ClassSDict *cl,FTextStream &t) { ClassSDict::Iterator cli(*cl); ClassDef *cd; - QCString title = "Classes"; + QCString title = theTranslator->trClasses(); if (cli.toFirst()) { - t << " " << endl; + t << "
" << endl; t << " " << title << " " << endl; } for (cli.toFirst();(cd=cli.current());++cli) @@ -926,6 +938,12 @@ static void writeInnerClasses(const ClassSDict *cl,FTextStream &t) t << " " << endl; t << " " << "struct " << convertToXML(cd->name()) << ""; t << "" << endl; + if (cd->briefDescription()) + { + t << ""; + writeDocbookString(t,cd->briefDescription()); + t << "" << endl; + } t << " " << endl; t << " " << endl; t << " " << endl; @@ -933,7 +951,7 @@ static void writeInnerClasses(const ClassSDict *cl,FTextStream &t) } if (cli.toFirst()) { - t << " " << endl; + t << "
" << endl; } } } @@ -944,7 +962,7 @@ static void writeInnerNamespaces(const NamespaceSDict *nl,FTextStream &t) { NamespaceSDict::Iterator nli(*nl); NamespaceDef *nd; - QCString title = "Namespaces"; + QCString title = theTranslator->trNamespaces(); if (nli.toFirst()) { @@ -978,7 +996,7 @@ static void writeInnerFiles(const FileList *fl,FTextStream &t) { QListIterator fli(*fl); FileDef *fd; - QCString title = "Files"; + QCString title = theTranslator->trFile(TRUE,TRUE); if (fli.toFirst()) { @@ -1028,7 +1046,7 @@ static void writeInnerGroups(const GroupList *gl,FTextStream &t) if (gli.toFirst()) { t << " " << endl; - t << " Modules" << endl; + t << " " << theTranslator->trModules() << "" << endl; t << " " << endl; t << " " << endl; t << " " << endl; @@ -1055,7 +1073,7 @@ static void writeInnerDirs(const DirList *dl,FTextStream &t) { QListIterator subdirs(*dl); DirDef *subdir; - QCString title = "Directories"; + QCString title = theTranslator->trDirectories(); if (subdirs.toFirst()) { t << " " << endl; @@ -1217,18 +1235,23 @@ static void generateDocbookForClass(ClassDef *cd,FTextStream &ti) generateDocbookSection(cd,t,ml,g_docbookSectionMapper.find(ml->listType())); } } - if (cd->briefDescription()) + + if(Config_getBool("REPEAT_BRIEF")) { - t << " " << endl; - t << " Brief Description" << endl; - writeDocbookDocBlock(t,cd->briefFile(),cd->briefLine(),cd,0,cd->briefDescription()); - t << " " << endl; + if (cd->briefDescription()) + { + t << " " << endl; + // A title as 'Brief Description' may not be necessary. + //t << " " << theTranslator->trBriefDescription() << "" << endl; + writeDocbookDocBlock(t,cd->briefFile(),cd->briefLine(),cd,0,cd->briefDescription()); + t << " " << endl; + } } if (cd->documentation()) { t << " " << endl; - t << " Detailed Description" << endl; + t << " " << theTranslator->trDetailedDescription() << "" << endl; writeDocbookDocBlock(t,cd->docFile(),cd->docLine(),cd,0,cd->documentation()); t << " Definition at line " << cd->getDefLine() << " of file " << stripPath(cd->getDefFileName()) << "" << endl; t << " The Documentation for this struct was generated from the following file: " << endl; @@ -1336,18 +1359,21 @@ static void generateDocbookForNamespace(NamespaceDef *nd,FTextStream &ti) } } - if (nd->briefDescription()) + if(Config_getBool("REPEAT_BRIEF")) { - t << " " << endl; - t << " Brief Description" << endl; - writeDocbookDocBlock(t,nd->briefFile(),nd->briefLine(),nd,0,nd->briefDescription()); - t << " " << endl; + if (nd->briefDescription()) + { + t << " " << endl; + //t << " " << theTranslator->trBriefDescription() << "" << endl; + writeDocbookDocBlock(t,nd->briefFile(),nd->briefLine(),nd,0,nd->briefDescription()); + t << " " << endl; + } } if (nd->documentation()) { t << " " << endl; - t << " Detailed Description" << endl; + t << " " << theTranslator->trDetailedDescription() << "" << endl; writeDocbookDocBlock(t,nd->docFile(),nd->docLine(),nd,0,nd->documentation()); t << " Definition at line " << nd->getDefLine() << " of file " << stripPath(nd->getDefFileName()) << "" << endl; t << " The Documentation for this struct was generated from the following file: " << endl; @@ -1473,7 +1499,7 @@ static void generateDocbookForFile(FileDef *fd,FTextStream &ti) } t << " " << endl; - t << " Detailed Description" << endl; + t << " " << theTranslator->trDetailedDescription() << "" << endl; writeDocbookDocBlock(t,fd->briefFile(),fd->briefLine(),fd,0,fd->briefDescription()); writeDocbookDocBlock(t,fd->docFile(),fd->docLine(),fd,0,fd->documentation()); if (Config_getBool("FULL_PATH_NAMES")) @@ -1545,18 +1571,18 @@ static void generateDocbookForGroup(GroupDef *gd,FTextStream &ti) if (gd->briefDescription()) { - t << " " << endl; - t << " Brief Description" << endl; + //t << "
" << endl; + //t << " " << theTranslator->trBriefDescription() << "" << endl; writeDocbookDocBlock(t,gd->briefFile(),gd->briefLine(),gd,0,gd->briefDescription()); - t << " " << endl; + //t << "
" << endl; } if (gd->documentation()) { - t << " " << endl; - t << " Detailed Description" << endl; + t << "
" << endl; + t << " " << theTranslator->trDetailedDescription() << "" << endl; writeDocbookDocBlock(t,gd->docFile(),gd->docLine(),gd,0,gd->documentation()); - t << " " << endl; + t << "
" << endl; } writeInnerFiles(gd->getFiles(),t); @@ -1623,8 +1649,7 @@ static void generateDocbookForDir(DirDef *dd,FTextStream &ti) writeDocbookHeader_ID(t, dd->getOutputFileBase()); t << " "; - writeDocbookString(t, dd->displayName()); - t << " Directory Reference"; + t << theTranslator->trDirReference(dd->displayName()); t << "" << endl; if (Config_getBool("DIRECTORY_GRAPH") && Config_getBool("HAVE_DOT")) { @@ -1637,7 +1662,7 @@ static void generateDocbookForDir(DirDef *dd,FTextStream &ti) writeInnerFiles(dd->getFiles(),t); t << " " << endl; - t << " Detailed Description" << endl; + t << " " << theTranslator->trDetailedDescription() << "" << endl; writeDocbookDocBlock(t,dd->briefFile(),dd->briefLine(),dd,0,dd->briefDescription()); writeDocbookDocBlock(t,dd->docFile(),dd->docLine(),dd,0,dd->documentation()); t << " Directory location is " << dd->name() << "" << endl; @@ -1691,7 +1716,15 @@ static void generateDocbookForPage(PageDef *pd,FTextStream &ti,bool isExample) } else { - QCString pid = pageName+"_1"+pageName; + QCString pid; + if(isExample) + { + pid = pageName; + } + else + { + pid = pageName+"_1"+pageName; + } writeDocbookHeader_ID(t, pid); } @@ -1849,7 +1882,7 @@ void generateDocbook() if (gli.toFirst()) { t << " " << endl; - t << " Module Documentation" << endl; + t << " " << theTranslator->trModuleDocumentation() << "" << endl; } for (;(gd=gli.current());++gli) @@ -1874,7 +1907,7 @@ void generateDocbook() if (cli.toFirst()) { t << " " << endl; - t << " Class Documentation" << endl; + t << " " << theTranslator->trClassDocumentation() << "" << endl; } for (cli.toFirst();(cd=cli.current());++cli) @@ -1901,7 +1934,7 @@ void generateDocbook() if (fnli.toFirst()) { t << " " << endl; - t << " File Documentation" << endl; + t << " " << theTranslator->trFileDocumentation() << "" << endl; } for (;(fn=fnli.current());++fnli) @@ -1932,7 +1965,7 @@ void generateDocbook() if (sdi.toFirst()) { t << " " << endl; - t << " Directory Documentation" << endl; + t << " " << theTranslator->trDirDocumentation() << "" << endl; } for (sdi.toFirst();(dir=sdi.current());++sdi) @@ -1958,7 +1991,7 @@ void generateDocbook() if (pdi.toFirst()) { t << " " << endl; - t << " Example Documentation" << endl; + t << " " << theTranslator->trExampleDocumentation() << "" << endl; } for (pdi.toFirst();(pd=pdi.current());++pdi) diff --git a/src/docbookvisitor.cpp b/src/docbookvisitor.cpp index a227dd8..8609347 100644 --- a/src/docbookvisitor.cpp +++ b/src/docbookvisitor.cpp @@ -1028,6 +1028,8 @@ void DocbookDocVisitor::visitPre(DocParamSect *s) } m_t << " " << endl; m_t << " " << endl; + m_t << " " << endl; + m_t << " " << endl; m_t << " " << endl; } -- cgit v0.12