Bug 719639 - @xrefitem with empty heading string

Adjusted documentation and in case the title is the empty string in a DocXRefItem the visitPre and visitPost do nothing.

8 files changed, 43 insertions, 8 deletions

diff --git a/doc/commands.doc b/doc/commands.doc
index b53c9d7..d13c68b 100644
--- a/doc/commands.doc
+++ b/doc/commands.doc
@@ -230,7 +230,7 @@ Structural indicators
   any of the commands.
 
   The title is optional, so this command can also be used to add a number of
-  entities to an existing group using \@{ and \@} like this:
+  entities to an existing group using \c \@{ and \c \@} like this:
 
 \verbatim
   /*! \addtogroup mygrp
@@ -1740,6 +1740,26 @@ void setPosition(double x,double y,double z,double t)
  Note the use of escaped quotes for the second and third argument of the
  \c \\xrefitem command.
 
+ In case parameter "(heading)" is the empty string no heading is generated. This can be useful
+ when used in combination with the \ref cmdpage "\\page" command e.g.
+\verbatim
+/** @page my_errors My Errors
+ *  @brief Errors page
+ *
+ *  Errors page contents.
+ */
+
+/** \error ERROR 101: in case a file can not be opened.
+    Check about file system read/write access. */
+#define MY_ERR_CANNOT_OPEN_FILE                   101
+
+/** \error ERROR 102: in case a file can not be closed.
+    Check about file system read/write access. */
+#define MY_ERR_CANNOT_CLOSE_FILE                  102
+\endverbatim
+ with \c \\error defined as
+ \verbatim ALIASES += "error=\xrefitem my_errors \"\" \"\"" \endverbatim
+
 <hr>
 
 \htmlonly <center> \endhtmlonly
diff --git a/src/docbookvisitor.cpp b/src/docbookvisitor.cpp
index 402f3c0..151f12d 100644
--- a/src/docbookvisitor.cpp
+++ b/src/docbookvisitor.cpp
@@ -1160,6 +1160,7 @@ void DocbookDocVisitor::visitPost(DocParamList *)
 void DocbookDocVisitor::visitPre(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
   m_t << "<para><link linkend=\"";
   m_t << x->file() << "_1" << x->anchor();
   m_t << "\">";
@@ -1168,9 +1169,10 @@ void DocbookDocVisitor::visitPre(DocXRefItem *x)
   m_t << " ";
 }
 
-void DocbookDocVisitor::visitPost(DocXRefItem *)
+void DocbookDocVisitor::visitPost(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
   m_t << "</para>";
 }
 
diff --git a/src/htmldocvisitor.cpp b/src/htmldocvisitor.cpp
index 601b665..ecdafe6 100644
--- a/src/htmldocvisitor.cpp
+++ b/src/htmldocvisitor.cpp
@@ -1777,6 +1777,8 @@ void HtmlDocVisitor::visitPost(DocParamList *)
 void HtmlDocVisitor::visitPre(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
+
   forceEndParagraph(x);
   bool anonymousEnum = x->file()=="@";
   if (!anonymousEnum)
@@ -1798,6 +1800,7 @@ void HtmlDocVisitor::visitPre(DocXRefItem *x)
 void HtmlDocVisitor::visitPost(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
   m_t << "</dd></dl>" << endl;
   forceStartParagraph(x);
 }
diff --git a/src/latexdocvisitor.cpp b/src/latexdocvisitor.cpp
index e68a51b..e6448b1 100644
--- a/src/latexdocvisitor.cpp
+++ b/src/latexdocvisitor.cpp
@@ -1515,6 +1515,7 @@ void LatexDocVisitor::visitPost(DocParamList *pl)
 void LatexDocVisitor::visitPre(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
   m_t << "\\begin{DoxyRefDesc}{";
   filter(x->title());
   m_t << "}" << endl;
@@ -1534,9 +1535,10 @@ void LatexDocVisitor::visitPre(DocXRefItem *x)
   m_t << "}]";
 }
 
-void LatexDocVisitor::visitPost(DocXRefItem *)
+void LatexDocVisitor::visitPost(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
   m_t << "\\end{DoxyRefDesc}" << endl;
 }
 
diff --git a/src/mandocvisitor.cpp b/src/mandocvisitor.cpp
index 238233c..d4da7aa 100644
--- a/src/mandocvisitor.cpp
+++ b/src/mandocvisitor.cpp
@@ -933,6 +933,7 @@ void ManDocVisitor::visitPost(DocParamList *pl)
 void ManDocVisitor::visitPre(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
   if (!m_firstCol)
   { 
     m_t << endl;
@@ -944,9 +945,10 @@ void ManDocVisitor::visitPre(DocXRefItem *x)
   m_t << ".RS 4" << endl;
 }
 
-void ManDocVisitor::visitPost(DocXRefItem *)
+void ManDocVisitor::visitPost(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
   if (!m_firstCol) m_t << endl;
   m_t << ".RE" << endl;
   m_t << ".PP" << endl;
diff --git a/src/perlmodgen.cpp b/src/perlmodgen.cpp
index 81e41a8..dd0dbbb 100644
--- a/src/perlmodgen.cpp
+++ b/src/perlmodgen.cpp
@@ -1349,7 +1349,7 @@ void PerlModDocVisitor::visitPost(DocParamList *)
     .closeHash();
 }
 
-void PerlModDocVisitor::visitPre(DocXRefItem *)
+void PerlModDocVisitor::visitPre(DocXRefItem *x)
 {
 #if 0
   m_output.add("<xrefsect id=\"");
@@ -1360,12 +1360,14 @@ void PerlModDocVisitor::visitPre(DocXRefItem *)
   m_output.add("</xreftitle>");
   m_output.add("<xrefdescription>");
 #endif
+  if (!(x->title().length())) return;
   openItem("xrefitem");
   openSubBlock("content");
 }
 
-void PerlModDocVisitor::visitPost(DocXRefItem *)
+void PerlModDocVisitor::visitPost(DocXRefItem *x)
 {
+  if (!(x->title().length())) return;
   closeSubBlock();
   closeItem();
 #if 0
diff --git a/src/rtfdocvisitor.cpp b/src/rtfdocvisitor.cpp
index 5d73c57..d83d8c0 100644
--- a/src/rtfdocvisitor.cpp
+++ b/src/rtfdocvisitor.cpp
@@ -1579,6 +1579,7 @@ void RTFDocVisitor::visitPost(DocParamList *pl)
 void RTFDocVisitor::visitPre(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
   bool anonymousEnum = x->file()=="@";
   DBG_RTF("{\\comment RTFDocVisitor::visitPre(DocXRefItem)}\n");
   m_t << "{"; // start param list
@@ -1624,9 +1625,10 @@ void RTFDocVisitor::visitPre(DocXRefItem *x)
   m_lastIsPara=FALSE;
 }
 
-void RTFDocVisitor::visitPost(DocXRefItem *)
+void RTFDocVisitor::visitPost(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
   DBG_RTF("{\\comment RTFDocVisitor::visitPost(DocXRefItem)}\n");
   m_t << "\\par" << endl;
   decIndentLevel();
diff --git a/src/xmldocvisitor.cpp b/src/xmldocvisitor.cpp
index e38a204..c4357f6 100644
--- a/src/xmldocvisitor.cpp
+++ b/src/xmldocvisitor.cpp
@@ -1012,6 +1012,7 @@ void XmlDocVisitor::visitPost(DocParamList *)
 void XmlDocVisitor::visitPre(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
   m_t << "<xrefsect id=\"";
   m_t << x->file() << "_1" << x->anchor();
   m_t << "\">";
@@ -1021,9 +1022,10 @@ void XmlDocVisitor::visitPre(DocXRefItem *x)
   m_t << "<xrefdescription>";
 }
 
-void XmlDocVisitor::visitPost(DocXRefItem *)
+void XmlDocVisitor::visitPost(DocXRefItem *x)
 {
   if (m_hide) return;
+  if (!(x->title().length())) return;
   m_t << "</xrefdescription>";
   m_t << "</xrefsect>";
 }