Orb/Doxygen/doc/doxywizard_usage.doc
author Jonathan Harrington <jonathan.harrington@nokia.com>
Wed, 11 Aug 2010 14:49:30 +0100
changeset 4 468f4c8d3d5b
parent 0 42188c7ea2d9
permissions -rw-r--r--
Orb version 0.2.0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
0
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
     1
/******************************************************************************
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
     2
 *
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
     3
 * 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
     4
 *
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
     5
 * Copyright (C) 1997-2008 by Dimitri van Heesch.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
     6
 *
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
     7
 * Permission to use, copy, modify, and distribute this software and its
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
     8
 * documentation under the terms of the GNU General Public License is hereby 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
     9
 * granted. No representations are made about the suitability of this software 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    10
 * for any purpose. It is provided "as is" without express or implied warranty.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    11
 * See the GNU General Public License for more details.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    12
 *
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    13
 * Documents produced by Doxygen are derivative works derived from the
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    14
 * input used in their production; they are not affected by this license.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    15
 *
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    16
 */
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    17
/*! \page doxywizard_usage Doxywizard usage
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    18
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    19
Doxywizard is a GUI front-end for configuring and running doxygen. 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    20
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    21
When you start doxywizard it will display the main window 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    22
(the actual look depends on the OS used).
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    23
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    24
\image html doxywizard_main.png "Main window"
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    25
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    26
The windows shows the steps to take to configure and run doxygen.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    27
The first step is to choose one of the ways to configure doxygen.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    28
<dl>
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    29
<dt>Wizard<dd>Click this button to quickly configure the most important 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    30
    settings and leave the rest of the options to their defaults.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    31
<dt>Expert<dd>Click this button to to gain access to the 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    32
    \ref config "full range of configuration options".
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    33
<dt>Load<dd>Click this button to load an existing configuration file 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    34
    from disk.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    35
</dl>
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    36
Note that you can select multiple buttons in a row, for instance to first 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    37
configure doxygen using the Wizard and then fine tune the settings via 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    38
the Expert.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    39
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    40
After doxygen is configured you need to save the configuration as a file
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    41
to disk. This second step allows doxygen to use the configuration 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    42
and has the additional advantage that the configuration can be reused 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    43
to run doxygen with the same settings at a later point in time.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    44
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    45
Since some configuration options may use relative paths, the next step is
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    46
to select a directory from which to run doxygen. This is typically the root
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    47
of the source tree and will most of the time already be filled in correctly.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    48
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    49
Once the configuration file is saved and the working directory is set, you
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    50
can run doxygen based on the selected settings. Do this by pressing the
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    51
"Start" button. Once doxygen runs you can cancel it by clicking the same
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    52
button again. The output produced by doxygen is captured and shown in a log
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    53
window. Once doxygen finishes, the log can be saved as a text file.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    54
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    55
<h3>The Wizard Dialog</h3>
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    56
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    57
If you select the Wizard button in step 1, then a dialog with
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    58
a number of tabs will appear.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    59
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    60
\image html doxywizard_page1.png "Wizard dialog: Project settings"
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    61
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    62
The fields in the project tab speak for themselves. Once doxygen has finished
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    63
the Destination directory is where to look for the results. Doxygen will
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    64
put each output format in a separate sub-directory.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    65
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    66
\image html doxywizard_page2.png "Wizard dialog: Mode of operating"
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    67
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    68
The mode tab allows you to select how doxygen will look at your sources.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    69
The default is to only look for things that have been documented. 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    70
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    71
You can also select how doxygen should present the results. 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    72
The latter does not affect the way doxygen parses your source code.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    73
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    74
\image html doxywizard_page3.png "Wizard dialog: Output to produce"
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    75
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    76
You can select one or more of the output formats that doxygen should
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    77
produce. For HTML and LaTeX there are additional options. 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    78
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    79
\image html doxywizard_page4.png "Wizard dialog: Diagrams to generate"
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    80
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    81
Doxygen can produce a number of diagrams. Using the diagrams tab you
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    82
can select which ones to generate. For most diagrams the 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    83
dot tool of the <a href="http://www.graphviz.org">GraphViz</a> package
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    84
is needed (if you use the binary packages for MacOSX this
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    85
tool is already included).
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    86
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    87
<h3>Expert dialog</h3>
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    88
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    89
The Expert dialog has a number of tab fields, one
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    90
for each section in the configuration file. Each tab-field
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    91
contains a number of lines, one for each configuration option in
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    92
that section. 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    93
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    94
The kind of input widget depends on the type of the configuration option. 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    95
<ul>
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    96
<li>For each boolean option (those options that are answered with YES or 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    97
    NO in the configuration file) there is a check-box. 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    98
<li>For items taking one of a fixed set of values (like 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
    99
    \ref cfg_output_language "OUTPUT_LANGUAGE") a combo box is used.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   100
<li>For items taking an integer value from a range, a spinbox is used.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   101
<li>For free form string-type options there is a one line edit field
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   102
<li>For options taking a lists of strings, a one line edit field is 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   103
    available, with a `+' button to add this string to the list and 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   104
    a `-' button to remove the selected string from the list. There 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   105
    is also a `*' button that, when pressed, 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   106
    replaces the selected item in the list with the string entered in the 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   107
    edit field. 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   108
<li>For file and folder entries, there are special buttons 
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   109
    that start a file selection dialog.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   110
</ul>
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   111
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   112
\image html doxywizard_expert.png "Some options from the Expert dialog"
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   113
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   114
The get additional information about the meaning of an option, click
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   115
on the "Help" button at the bottom right of the dialog and then on the
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   116
item. A tooltip with additional information will appear.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   117
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   118
<h3>Menu options</h3>
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   119
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   120
The GUI front-end has a menu with a couple of useful items
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   121
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   122
\image html doxywizard_menu.png "File menu"
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   123
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   124
<dl>
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   125
<dt>Open...<dd>This is the same as the "Load" button in the main window
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   126
    and allows to open a configuration file from disk.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   127
<dt>Save as..<dd>This is the same as the "Save" button in the main window
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   128
    and can be used to save the current configuration settings to disk.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   129
<dt>Recent configurations<dd>Allow to quickly load a recently saved
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   130
    configuration.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   131
<dt>Set as default...<dd>Stores the current configuration settings as the
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   132
    default to use next time the GUI is started. You will be asked to
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   133
    confirm the action.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   134
<dt>Reset...<dd>Restores the factory defaults as the default settings to use.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   135
    You will be asked to confirm the action.
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   136
</dl>
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   137
42188c7ea2d9 Initial contribution of ORB delivering Feature bug 1460
szarinda <>
parents:
diff changeset
   138
*/