Skip to content

D
doxverilog
Commit 1a403d80 authored by zmhuang's avatar zmhuang
Browse files
Options

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
parent 540f0b66
Hide whitespace changes
Inline Side-by-side
Showing with 139 additions and 104 deletions
src/docbookgen.cpp
View file @ 1a403d80
......@@ -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)
......
src/docbookvisitor.cpp
View file @ 1a403d80
......@@ -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;
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment