lists.doc 2.97 KB
Newer Older
Dimitri van Heesch's avatar
Dimitri van Heesch committed
1 2
/*! \page lists Lists

3
Doxygen provides a number of ways to create lists of items.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
4 5 6

<b>Using dashes</b>

7 8
By putting a number of column-aligned minus (-) signs at the start of a 
line, a bullet list will automatically be generated. Instead of the minus
9
sign also plus (+) or asterisk (\*) can be used.
10

11 12 13 14 15
Numbered lists can also be generated by using a minus followed by a hash 
or by using a number followed by a dot.

Nesting of lists is allowed and is based on indentation of the items.<p>
Here is an example:
16

Dimitri van Heesch's avatar
Dimitri van Heesch committed
17 18 19 20 21 22 23 24 25
\verbatim
  /*! 
   *  A list of events:
   *    - mouse events
   *         -# mouse move event
   *         -# mouse click event\n
   *            More info about the click event.
   *         -# mouse double click event
   *    - keyboard events
26 27
   *         1. key down event
   *         2. key up event
Dimitri van Heesch's avatar
Dimitri van Heesch committed
28 29 30 31 32 33 34 35 36 37 38 39 40
   *
   *  More text here.
   */
\endverbatim
     The result will be:

     A list of events:
       - mouse events
            -# mouse move event
            -# mouse click event\n
               More info about the click event.
            -# mouse double click event
       - keyboard events
41 42
            1. key down event
            2. key up event
Dimitri van Heesch's avatar
Dimitri van Heesch committed
43 44 45
     
     More text here.

46 47 48
If you use tabs for indentation within lists, please make sure 
that \ref cfg_tab_size "TAB_SIZE" in the configuration file is set to 
the correct tab size.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
49

Dimitri van Heesch's avatar
Dimitri van Heesch committed
50
You can end a list by starting a new paragraph or 
51
by putting a dot (.) on an empty line at the same indentation level as the 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
52 53 54 55 56 57 58 59 60 61 62 63 64
list you would like to end.

Here is an example that speaks for itself:

\verbatim
/**
 * Text before the list
 * - list item 1
 *   - sub item 1
 *     - sub sub item 1
 *     - sub sub item 2
 *     . 
 *     The dot above ends the sub sub item list.
65
 *
Dimitri van Heesch's avatar
Dimitri van Heesch committed
66 67 68
 *     More text for the first sub item
 *   .
 *   The dot above ends the first sub item.
69
 *
Dimitri van Heesch's avatar
Dimitri van Heesch committed
70 71 72 73 74 75 76 77 78 79 80
 *   More text for the first list item
 *   - sub item 2
 *   - sub item 3
 * - list item 2
 * .
 * More text in the same paragraph.
 *
 * More text in a new paragraph.
 */
\endverbatim

Dimitri van Heesch's avatar
Dimitri van Heesch committed
81 82 83
<b>Using HTML commands</b>

If you like you can also use HTML commands inside the documentation
84
blocks. 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
85 86 87 88 89 90 91 92 93

Here is the above example with HTML commands:
\verbatim
  /*! 
   *  A list of events:
   *  <ul>
   *  <li> mouse events
   *     <ol>
   *     <li>mouse move event
94
   *     <li>mouse click event<br>
Dimitri van Heesch's avatar
Dimitri van Heesch committed
95 96 97 98 99 100 101 102 103 104 105 106 107
   *         More info about the click event.
   *     <li>mouse double click event
   *     </ol>
   *  <li> keyboard events
   *     <ol>     
   *     <li>key down event
   *     <li>key up event
   *     </ol>
   *  </ul>
   *  More text here.
   */
\endverbatim

108
\note In this case the indentation is not important.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
109

110
<b>Using \\arg or \\li</b>
Dimitri van Heesch's avatar
Dimitri van Heesch committed
111

112
For compatibility with the Qt Software's internal documentation tool qdoc and
Dimitri van Heesch's avatar
Dimitri van Heesch committed
113
with KDoc, doxygen has two commands that can be used to create simple
114
unnested lists. 
Dimitri van Heesch's avatar
Dimitri van Heesch committed
115

116
See \ref cmdarg "\\arg" and \ref cmdli "\\li" for more info.
Dimitri van Heesch's avatar
Dimitri van Heesch committed
117 118 119 120 121 122 123 124 125

\htmlonly
Go to the <a href="grouping.html">next</a> section or return to the
 <a href="index.html">index</a>.
\endhtmlonly

*/