doc/lists.doc

   1 /*! \page lists Lists
   2
   3 Doxygen provides a number of ways to create lists of items.
   4
   5 <b>Using dashes</b>
   6
   7 By putting a number of column-aligned minus (-) signs at the start of a
   8 line, a bullet list will automatically be generated. Instead of the minus
   9 sign also plus (+) or asterisk (\*) can be used.
  10
  11 Numbered lists can also be generated by using a minus followed by a hash
  12 or by using a number followed by a dot.
  13
  14 Nesting of lists is allowed and is based on indentation of the items.<p>
  15 Here is an example:
  16
  17 \verbatim
  18   /*!
  19    *  A list of events:
  20    *    - mouse events
  21    *         -# mouse move event
  22    *         -# mouse click event\n
  23    *            More info about the click event.
  24    *         -# mouse double click event
  25    *    - keyboard events
  26    *         1. key down event
  27    *         2. key up event
  28    *
  29    *  More text here.
  30    */
  31 \endverbatim
  32      The result will be:
  33
  34      A list of events:
  35        - mouse events
  36             -# mouse move event
  37             -# mouse click event\n
  38                More info about the click event.
  39             -# mouse double click event
  40        - keyboard events
  41             1. key down event
  42             2. key up event
  43
  44      More text here.
  45
  46 If you use tabs for indentation within lists, please make sure
  47 that \ref cfg_tab_size "TAB_SIZE" in the configuration file is set to
  48 the correct tab size.
  49
  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
  52 list you would like to end.
  53
  54 Here is an example that speaks for itself:
  55
  56 \verbatim
  57 /**
  58  * Text before the list
  59  * - list item 1
  60  *   - sub item 1
  61  *     - sub sub item 1
  62  *     - sub sub item 2
  63  *     .
  64  *     The dot above ends the sub sub item list.
  65  *
  66  *     More text for the first sub item
  67  *   .
  68  *   The dot above ends the first sub item.
  69  *
  70  *   More text for the first list item
  71  *   - sub item 2
  72  *   - sub item 3
  73  * - list item 2
  74  * .
  75  * More text in the same paragraph.
  76  *
  77  * More text in a new paragraph.
  78  */
  79 \endverbatim
  80
  81 <b>Using HTML commands</b>
  82
  83 If you like you can also use HTML commands inside the documentation
  84 blocks.
  85
  86 Here is the above example with HTML commands:
  87 \verbatim
  88   /*!
  89    *  A list of events:
  90    *  <ul>
  91    *  <li> mouse events
  92    *     <ol>
  93    *     <li>mouse move event
  94    *     <li>mouse click event<br>
  95    *         More info about the click event.
  96    *     <li>mouse double click event
  97    *     </ol>
  98    *  <li> keyboard events
  99    *     <ol>
 100    *     <li>key down event
 101    *     <li>key up event
 102    *     </ol>
 103    *  </ul>
 104    *  More text here.
 105    */
 106 \endverbatim
 107
 108 \note In this case the indentation is not important.
 109
 110 <b>Using \\arg or \\li</b>
 111
 112 For compatibility with the Qt Software's internal documentation tool qdoc and
 113 with KDoc, doxygen has two commands that can be used to create simple
 114 unnested lists.
 115
 116 See \ref cmdarg "\\arg" and \ref cmdli "\\li" for more info.
 117
 118 \htmlonly
 119 Go to the <a href="grouping.html">next</a> section or return to the
 120  <a href="index.html">index</a>.
 121 \endhtmlonly
 122
 123 */
 124
 125