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.

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

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>";
 }
 

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);
 }

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;
 }
 

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;

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

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();

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>";
 }