diff options
author | zmhuang <bf533@126.com> | 2014-12-08 11:19:32 (GMT) |
---|---|---|
committer | zmhuang <bf533@126.com> | 2014-12-16 06:49:13 (GMT) |
commit | 1a403d80160458091bab7c442e54f836c0b90bca (patch) | |
tree | f68256a95fd0b39f38643d755a2b7458f13e24ec /src | |
parent | 540f0b66972c03fd53c97174e1680230b8dd4026 (diff) | |
download | Doxygen-1a403d80160458091bab7c442e54f836c0b90bca.zip Doxygen-1a403d80160458091bab7c442e54f836c0b90bca.tar.gz Doxygen-1a403d80160458091bab7c442e54f836c0b90bca.tar.bz2 |
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
Diffstat (limited to 'src')
-rw-r--r-- | src/docbookgen.cpp | 241 | ||||
-rw-r--r-- | 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 << "</literallayout>" << endl; + if (md->briefDescription()) + { + t << "<para><emphasis>"; + writeDocbookString(t,md->briefDescription()); + t << "</emphasis></para>" << 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()) << "</link>"; + if (md->briefDescription()) + { + t << "<para><emphasis>"; + writeDocbookString(t,md->briefDescription()); + t << "</emphasis></para>" << 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()) << "</link>"; + if (md->briefDescription()) + { + t << "<para><emphasis>"; + writeDocbookString(t,md->briefDescription()); + t << "</emphasis></para>" << 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 << "<para><emphasis>"; + writeDocbookString(t,md->briefDescription()); + t << "</emphasis></para>" << endl; + } } else { @@ -631,7 +655,7 @@ static void generateDocbookForMember(MemberDef *md,FTextStream &t,Definition *de MemberListIterator emli(*enumFields); MemberDef *emd; t << " <formalpara>" << endl; - t << " <title>Enumerator:</title>" << endl; + t << " <title>" << theTranslator->trEnumerationValues() << ":</title>" << endl; t << " <variablelist>" << 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 << "</term>" << endl; t << " <listitem>" << endl; - t << " <para>"; - writeDocbookString(t,emd->briefDescription()); - t << "</para>" << endl; + if(Config_getBool("REPEAT_BRIEF")) + { + t << " <para>"; + writeDocbookString(t,emd->briefDescription()); + t << "</para>" << endl; + } t << " </listitem>" << endl; t << " </varlistentry>" << endl; } @@ -681,9 +708,12 @@ static void generateDocbookForMember(MemberDef *md,FTextStream &t,Definition *de } t << "_1" << md->anchor() << "\">" << endl; t << " <title>" << convertToXML(md->definition()) << "</title>"; - t << " <emphasis>"; - writeDocbookString(t,md->briefDescription()); - t << "</emphasis>" << endl; + if(Config_getBool("REPEAT_BRIEF")) + { + t << " <emphasis>"; + writeDocbookString(t,md->briefDescription()); + t << "</emphasis>" << 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 << " <title>" << convertToXML(md->definition()) << " " << convertToXML(md->argsString()) << "</title>"; - t << " <emphasis>"; - writeDocbookString(t,md->briefDescription()); - t << "</emphasis>" << endl; + if(Config_getBool("REPEAT_BRIEF")) + { + t << " <emphasis>"; + writeDocbookString(t,md->briefDescription()); + t << "</emphasis>" << 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 << " <title>" << convertToXML(md->definition()) << "</title>"; - t << " <emphasis>"; - writeDocbookString(t,md->briefDescription()); - t << "</emphasis>" << endl; + if(Config_getBool("REPEAT_BRIEF")) + { + t << " <emphasis>"; + writeDocbookString(t,md->briefDescription()); + t << "</emphasis>" << 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 << " <simplesect>" << endl; - t << " <title>" << desctitle << "</title>" << endl; - } - } - else if (desctitle=="Define Documentation") - { - if (doc_count > 0) + if (md->documentation().isEmpty() && !Config_getBool("REPEAT_BRIEF")) { - t << " <section>" << endl; - t << " <title>" << desctitle << "</title>" << endl; + continue; } - } - else - { + doc_count = 1; + break; + } + + if(doc_count == 0) + { + return; + } + + if (desctitle) + { t << " <section>" << endl; t << " <title>" << desctitle << "</title>" << endl; - } } } else { - t << " <simplesect>" << endl; + t << " <section>" << endl; if (header) { t << " <title>" << convertToXML(header) << "</title>" << 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 << " </simplesect>" << endl; - } - } - else if (desctitle=="Define Documentation") - { - if (doc_count > 0) - { - t << " </section>" << endl; - } - } - else - { t << " </section>" << endl; - } } } else { - t << " </simplesect>" << endl; + t << " </section>" << 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 << " <simplesect>" << endl; + t << " <section>" << endl; t << " <title> " << title << " </title>" << endl; } for (cli.toFirst();(cd=cli.current());++cli) @@ -926,6 +938,12 @@ static void writeInnerClasses(const ClassSDict *cl,FTextStream &t) t << " <listitem>" << endl; t << " <para>" << "struct <link linkend=\"" << classOutputFileBase(cd) << "\">" << convertToXML(cd->name()) << "</link>"; t << "</para>" << endl; + if (cd->briefDescription()) + { + t << "<para><emphasis>"; + writeDocbookString(t,cd->briefDescription()); + t << "</emphasis></para>" << endl; + } t << " </listitem>" << endl; t << " </itemizedlist>" << endl; t << " </para>" << endl; @@ -933,7 +951,7 @@ static void writeInnerClasses(const ClassSDict *cl,FTextStream &t) } if (cli.toFirst()) { - t << " </simplesect>" << endl; + t << " </section>" << 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<FileDef> 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 << " <simplesect>" << endl; - t << " <title>Modules</title>" << endl; + t << " <title>" << theTranslator->trModules() << "</title>" << endl; t << " </simplesect>" << endl; t << " <para>" << endl; t << " <itemizedlist>" << endl; @@ -1055,7 +1073,7 @@ static void writeInnerDirs(const DirList *dl,FTextStream &t) { QListIterator<DirDef> subdirs(*dl); DirDef *subdir; - QCString title = "Directories"; + QCString title = theTranslator->trDirectories(); if (subdirs.toFirst()) { t << " <simplesect>" << 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 << " <simplesect>" << endl; - t << " <title>Brief Description</title>" << endl; - writeDocbookDocBlock(t,cd->briefFile(),cd->briefLine(),cd,0,cd->briefDescription()); - t << " </simplesect>" << endl; + if (cd->briefDescription()) + { + t << " <simplesect>" << endl; + // A title as 'Brief Description' may not be necessary. + //t << " <title>" << theTranslator->trBriefDescription() << "</title>" << endl; + writeDocbookDocBlock(t,cd->briefFile(),cd->briefLine(),cd,0,cd->briefDescription()); + t << " </simplesect>" << endl; + } } if (cd->documentation()) { t << " <simplesect>" << endl; - t << " <title>Detailed Description</title>" << endl; + t << " <title>" << theTranslator->trDetailedDescription() << "</title>" << endl; writeDocbookDocBlock(t,cd->docFile(),cd->docLine(),cd,0,cd->documentation()); t << " <para>Definition at line " << cd->getDefLine() << " of file " << stripPath(cd->getDefFileName()) << "</para>" << endl; t << " <para>The Documentation for this struct was generated from the following file: </para>" << endl; @@ -1336,18 +1359,21 @@ static void generateDocbookForNamespace(NamespaceDef *nd,FTextStream &ti) } } - if (nd->briefDescription()) + if(Config_getBool("REPEAT_BRIEF")) { - t << " <simplesect>" << endl; - t << " <title>Brief Description</title>" << endl; - writeDocbookDocBlock(t,nd->briefFile(),nd->briefLine(),nd,0,nd->briefDescription()); - t << " </simplesect>" << endl; + if (nd->briefDescription()) + { + t << " <simplesect>" << endl; + //t << " <title>" << theTranslator->trBriefDescription() << "</title>" << endl; + writeDocbookDocBlock(t,nd->briefFile(),nd->briefLine(),nd,0,nd->briefDescription()); + t << " </simplesect>" << endl; + } } if (nd->documentation()) { t << " <simplesect>" << endl; - t << " <title>Detailed Description</title>" << endl; + t << " <title>" << theTranslator->trDetailedDescription() << "</title>" << endl; writeDocbookDocBlock(t,nd->docFile(),nd->docLine(),nd,0,nd->documentation()); t << " <para>Definition at line " << nd->getDefLine() << " of file " << stripPath(nd->getDefFileName()) << "</para>" << endl; t << " <para>The Documentation for this struct was generated from the following file: </para>" << endl; @@ -1473,7 +1499,7 @@ static void generateDocbookForFile(FileDef *fd,FTextStream &ti) } t << " <simplesect>" << endl; - t << " <title>Detailed Description</title>" << endl; + t << " <title>" << theTranslator->trDetailedDescription() << "</title>" << 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 << " <simplesect>" << endl; - t << " <title>Brief Description</title>" << endl; + //t << " <section>" << endl; + //t << " <title>" << theTranslator->trBriefDescription() << "</title>" << endl; writeDocbookDocBlock(t,gd->briefFile(),gd->briefLine(),gd,0,gd->briefDescription()); - t << " </simplesect>" << endl; + //t << " </section>" << endl; } if (gd->documentation()) { - t << " <simplesect>" << endl; - t << " <title>Detailed Description</title>" << endl; + t << " <section>" << endl; + t << " <title>" << theTranslator->trDetailedDescription() << "</title>" << endl; writeDocbookDocBlock(t,gd->docFile(),gd->docLine(),gd,0,gd->documentation()); - t << " </simplesect>" << endl; + t << " </section>" << endl; } writeInnerFiles(gd->getFiles(),t); @@ -1623,8 +1649,7 @@ static void generateDocbookForDir(DirDef *dd,FTextStream &ti) writeDocbookHeader_ID(t, dd->getOutputFileBase()); t << " <title>"; - writeDocbookString(t, dd->displayName()); - t << " Directory Reference"; + t << theTranslator->trDirReference(dd->displayName()); t << "</title>" << 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 << " <simplesect>" << endl; - t << " <title>Detailed Description</title>" << endl; + t << " <title>" << theTranslator->trDetailedDescription() << "</title>" << endl; writeDocbookDocBlock(t,dd->briefFile(),dd->briefLine(),dd,0,dd->briefDescription()); writeDocbookDocBlock(t,dd->docFile(),dd->docLine(),dd,0,dd->documentation()); t << " <para>Directory location is " << dd->name() << "</para>" << 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 << " <chapter>" << endl; - t << " <title>Module Documentation</title>" << endl; + t << " <title>" << theTranslator->trModuleDocumentation() << "</title>" << endl; } for (;(gd=gli.current());++gli) @@ -1874,7 +1907,7 @@ void generateDocbook() if (cli.toFirst()) { t << " <chapter>" << endl; - t << " <title>Class Documentation</title>" << endl; + t << " <title>" << theTranslator->trClassDocumentation() << "</title>" << endl; } for (cli.toFirst();(cd=cli.current());++cli) @@ -1901,7 +1934,7 @@ void generateDocbook() if (fnli.toFirst()) { t << " <chapter>" << endl; - t << " <title>File Documentation</title>" << endl; + t << " <title>" << theTranslator->trFileDocumentation() << "</title>" << endl; } for (;(fn=fnli.current());++fnli) @@ -1932,7 +1965,7 @@ void generateDocbook() if (sdi.toFirst()) { t << " <chapter>" << endl; - t << " <title>Directory Documentation</title>" << endl; + t << " <title>" << theTranslator->trDirDocumentation() << "</title>" << endl; } for (sdi.toFirst();(dir=sdi.current());++sdi) @@ -1958,7 +1991,7 @@ void generateDocbook() if (pdi.toFirst()) { t << " <chapter>" << endl; - t << " <title>Example Documentation</title>" << endl; + t << " <title>" << theTranslator->trExampleDocumentation() << "</title>" << 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 << " </title>" << endl; m_t << " <tgroup cols=\"2\" align=\"left\" colsep=\"1\" rowsep=\"1\">" << endl; + m_t << " <colspec colwidth=\"1*\"/>" << endl; + m_t << " <colspec colwidth=\"4*\"/>" << endl; m_t << " <tbody>" << endl; } |