Added documentation for creating tables

doxygen · Aug 26, 2015 · 23faa44 · 23faa44
1 parent 883989f
commit 23faa44
Show file tree

Hide file tree

Showing 7 changed files with 105 additions and 4 deletions.
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -61,6 +61,7 @@ set(DOC_FILES
         faq.doc
         features.doc
         formulas.doc
+        tables.doc
         grouping.doc
         htmlcmds.doc
         index.doc

diff --git a/doc/Doxyfile b/doc/Doxyfile
@@ -34,7 +34,7 @@ ENABLE_PREPROCESSING = NO
 CASE_SENSE_NAMES  = NO
 IMAGE_PATH        = .
 INPUT             = index.doc install.doc starting.doc docblocks.doc markdown.doc \
-                    lists.doc grouping.doc formulas.doc diagrams.doc preprocessing.doc \
+                    lists.doc grouping.doc formulas.doc tables.doc diagrams.doc preprocessing.doc \
                     autolink.doc output.doc searching.doc extsearch.doc customize.doc custcmd.doc \
                     external.doc faq.doc trouble.doc features.doc \
 		    doxygen_usage.doc doxywizard_usage.doc \

diff --git a/doc/doxygen_manual.tex b/doc/doxygen_manual.tex
@@ -67,6 +67,8 @@
 \newcommand{\thisyear}{\the\year}
 \hfuzz=15pt
 \setlength{\emergencystretch}{15pt}
+\setlength{\parindent}{0pt}
+\setlength{\parskip}{0.2cm}
 \hbadness=750
 \tolerance=750
 \begin{document}
@@ -92,6 +94,7 @@ \chapter{Markdown}\label{markdown}\hypertarget{markdown}{}\input{markdown}
 \chapter{Lists}\label{lists}\hypertarget{lists}{}\input{lists}
 \chapter{Grouping}\label{grouping}\hypertarget{grouping}{}\input{grouping}
 \chapter{Including Formulas}\label{formulas}\hypertarget{formulas}{}\input{formulas}
+\chapter{Including Tables}\label{tables}\hypertarget{tables}{}\input{tables}
 \chapter{Graphs and diagrams}\label{diagrams}\hypertarget{diagrams}{}\input{diagrams}
 \chapter{Preprocessing}\label{preprocessing}\hypertarget{preprocessing}{}\input{preprocessing}
 \chapter{Automatic link generation}\label{autolink}\hypertarget{autolink}{}\input{autolink}

diff --git a/doc/formulas.doc b/doc/formulas.doc
@@ -105,7 +105,7 @@ file <code>formula.repository</code> that is written to the html directory to
 get rid of an incorrect formula.
 
 \htmlonly
-Go to the <a href="diagrams.html">next</a> section or return to the
+Go to the <a href="tables.html">next</a> section or return to the
  <a href="index.html">index</a>.
 \endhtmlonly
 

diff --git a/doc/tables.doc b/doc/tables.doc
@@ -0,0 +1,95 @@
+/******************************************************************************
+ *
+ *
+ *
+ * Copyright (C) 1997-2015 by Dimitri van Heesch.
+ *
+ * Permission to use, copy, modify, and distribute this software and its
+ * documentation under the terms of the GNU General Public License is hereby
+ * granted. No representations are made about the suitability of this software
+ * for any purpose. It is provided "as is" without express or implied warranty.
+ * See the GNU General Public License for more details.
+ *
+ * Documents produced by Doxygen are derivative works derived from the
+ * input used in their production; they are not affected by this license.
+ *
+ */
+/*! \page tables Including tables
+
+Doxygen supports two ways to put tables in the documentation.
+
+The easiest is to use the Markdown format as shown @ref md_tables "here".
+
+Although this format is easy to use and read, it is also rather limited.
+It supports only a simple grid of cells, while each cell is a
+single line of plain text.
+
+For more complex tables the HTML syntax can be used. Doxygen
+will process such tables and translate them to the various output formats
+(at least for the formats that do support tables such as HTML and \LaTeX).
+
+Here is an example of a complex table:
+
+\verbatim
+<table>
+<caption id="multi_row">Complex table</caption>
+<tr><th>Column 1                      <th>Column 2        <th>Column 3
+<tr><td rowspan="2">cell row=1+2,col=1<td>cell row=1,col=2<td>cell row=1,col=3
+<tr><td rowspan="2">cell row=2+3,col=2                    <td>cell row=2,col=3
+<tr><td>cell row=3,col=1                                  <td rowspan="2">cell row=3+4,col=3
+<tr><td colspan="2">cell row=4,col=1+2
+<tr><td>cell row=5,col=1              <td colspan="2">cell row=5,col=2+3
+<tr><td colspan="2" rowspan="2">cell row=6+7,col=1+2      <td>cell row=6,col=3
+<tr>                                                      <td>cell row=7,col=3
+<tr><td>cell row=8,col=1              <td>cell row=8,col=2\n
+  <table>
+    <tr><td>Inner cell row=1,col=1<td>Inner cell row=1,col=2
+    <tr><td>Inner cell row=2,col=1<td>Inner cell row=2,col=2
+  </table>
+  <td>cell row=8,col=3
+  <ul>
+    <li>Item 1
+    <li>Item 2
+  </ul>
+</table>
+\endverbatim
+
+It has a caption, table heading, various row and column spans,
+a nested table as one of the cells, and a item list in another cell.
+
+Note that the end tags (like `</td>`) are left out in the example above.
+This is allowed, and in the HTML output doxygen will be add the end tags again.
+
+The output will look as follows:
+
+<table>
+<caption id="multi_row">Complex table</caption>
+<tr><th>Column 1                      <th>Column 2        <th>Column 3
+<tr><td rowspan="2">cell row=1+2,col=1<td>cell row=1,col=2<td>cell row=1,col=3
+<tr><td rowspan="2">cell row=2+3,col=2                    <td>cell row=2,col=3
+<tr><td>cell row=3,col=1                                  <td rowspan="2">cell row=3+4,col=3
+<tr><td colspan="2">cell row=4,col=1+2
+<tr><td>cell row=5,col=1              <td colspan="2">cell row=5,col=2+3
+<tr><td colspan="2" rowspan="2">cell row=6+7,col=1+2      <td>cell row=6,col=3
+<tr>                                                      <td>cell row=7,col=3
+<tr><td>cell row=8,col=1              <td>cell row=8,col=2\n
+  <table>
+    <tr><td>Inner cell row=1,col=1<td>Inner cell row=1,col=2
+    <tr><td>Inner cell row=2,col=1<td>Inner cell row=2,col=2
+  </table>
+  <td>cell row=8,col=3
+  <ul>
+    <li>Item 1
+    <li>Item 2
+  </ul>
+</table>
+
+One can refer to the caption of the table using \ref cmdref "\\ref" using the caption's
+id as the label.
+
+\htmlonly
+Go to the <a href="diagrams.html">next</a> section or return to the
+ <a href="index.html">index</a>.
+\endhtmlonly
+
+*/
diff --git a/src/docparser.cpp b/src/docparser.cpp
@@ -585,7 +585,8 @@ static void detectNoDocumentedParams()
         g_memberDef->setHasDocumentedParams(TRUE);
       }
     }
-    //printf("Member %s hasReturnCommand=%d\n",g_memberDef->name().data(),g_hasReturnCommand);
+    //printf("Member %s hadDocumentedReturnType()=%d hasReturnCommand=%d\n",
+    //    g_memberDef->name().data(),g_memberDef->hasDocumentedReturnType(),g_hasReturnCommand);
     if (!g_memberDef->hasDocumentedReturnType() && // docs not yet found
         g_hasReturnCommand)
     {
@@ -602,7 +603,7 @@ static void detectNoDocumentedParams()
     {
       g_memberDef->setHasDocumentedReturnType(TRUE);
     }
-    if ( // see if return type is documented in a function w/o return type
+    else if ( // see if return type is documented in a function w/o return type
         g_memberDef->hasDocumentedReturnType() &&
         (returnType.isEmpty()              || // empty return type
          returnType.find("void")!=-1       || // void return type

diff --git a/templates/latex/doxygen.sty b/templates/latex/doxygen.sty
@@ -12,6 +12,7 @@
 \RequirePackage{longtable}
 \RequirePackage{tabu}
 \RequirePackage{tabularx}
+\RequirePackage{multirow}
 
 %---------- Internal commands used in this style file ----------------