Doxygen Basics

 Smooth sailing guaranteed






Overview

Doxygen is an application which runs on Linux or Windows. It makes documentation using specially formatted hints edited into the source code. The resultant documents are usually in html but can be in Latex (for printing) or several other file types.

Doxygen is free.

my notes   my screen shots etc on how to setup for a project
mark up   How to mark up your code. A quick intro.
user manual   click "Documenting the code" ; It also explains installation
graphics   graphics for Doxygen. Dependency graphs, calling graphs.
the website   find "download" on right of page


the Doxygen GUI "doxywizard"

Before running Doxygen, consider modifying the Config file to show
the current version number.  The config file is "Src/DoxygenConfig.dox" and
the entry I suggest you change is PROJECT_NUMBER, presently
"_4.3.2"

If the file type '.dox' is associated properly, you can just double click
on Src/DoxygenConfig.dox to start the GUI. ".dox" should be associated with
C:\Program Files\doxygen\bin\doxywizard.

When ready, double click on the config file and hit "Start" button.

Conventions
-----------
Doxygen comes from Linux land and uses forward slashes in paths,
eg: C:/Company/goodcode.c 


Strategy
--------
*IF* you use a single .h file to define public routines which will 
be instantiated in more than 1 .c file, then document that routine
only in the .h, not in either .c .  The problem is that multiple 
instances of such definitions will have Dox copying stuff from one
to another - probably not whatcha want.

To document a per-product routine, like InitHW(), find a shared
.h file (like General.h) to hold the documentation. This presumes
its interface and basic function are the same across all instances
of it.

When developing the docs for your source files, run Doxygen from
the GUI and hit "Save Log File". Use its warnings to guide you.
This repetitive operation is a improved by making a separate 
config file for just the files you're editing. See the section
entitled: "Iterating on the documentation you're adding".


Config'g with 'the Wizard'
--------------------------
The process of making the output files uses a "config file" and
the '07 releases of Doxygen include a program, "Doxygen GUI frontend",
which contains a "Wizard" and Config file editor/loader. The Wizard
does a good and quick job of defaulting this file. 

Tip: When asked to save the config, DON'T use the default
     name (doxyfile). It'll make it harder to have several
     config files and there'll be the constant threat of 
     accidentally overwriting your principle config file.
     Instead choose a name related to the project, perhaps
     noting that this is for the full set of files.

Tip: When asked to save the config, put it in a directory at the lowest
     directory holding the source of interest:eg .../src
     Give the config file an extension, like ".dox", and associate
     this file type with C:\Programs\doxygen\bin\doxywizard.exe,
     calling the file something like a "Doxygen Config" file.
     To restart the wizard, dbbl click on the .dox file.

Tip: after making a default config file, return to it, selecting
    'Expert'. You probably want to leave the 'html' output setting but
     deselect 'Latex'.  Note that there's no problem cloning a config
     file:
         cd longPath/Src
         cp nfr2config.dox franksConfig.dox  // example names
         edit franksConfig.dox     // to remove/add/change whatever
         // optional: make a shortcut in Wonders, drag it to the desktop
         // dbbl click on new config to go back to the wizard - to
         //     edit more and/or to run Doxygen.

Consider: you could make a Config file at the project level, eg:
     longPath/Src/xyz/ST_614/614Config.dox
     which defined inputs to be the local, product files and the
     support files in ../.. ; you'd probably want the Doxygen
     output directory to also be at the project level.

The following ---- sections correspond to the Tabs in the Expert
area. The fields shown often have definitions which pop-up as
mouseovers. Explore.

Project: --------------------------
   DOXYFILE_ENCODING		  left it at UTF-8
   PROJECT_NAME        Prj_4.3_Firmware   This shows up in the page header when printed. The underscores are needed.
   PROJECT_NUMBER      Prj_4.3.2   This appears in index.html when you 1st open results. I suggest you change this before every (meaningful) run.
   OUTPUT_DIRECTORY    ...Prj/doxygenOutputs    will go in html subdirectory
 _ CREATE_SUBDIRS      left this unchecked
   OUTPUT_LANGUAGE     left this at English
 x BRIEF_MEMBER_DESC   left this checked
 x REPEAT_BRIEF        left this checked
   ABBREVIATE_BRIEF    left this alone
 - ALWAYS_DETAILED_SEC
 - INLINE_INHERITED_MEMB
 - FULL_PATH_NAMES     Deselect this to make banner readable on your
                       resultant output files.
   STRIP_FROM_PATH     C:/ up to Prj

         thought this would strip from log messages but it didn't.


   STRIP_FROM_INC_PATH left this blank

 _ SHORT_NAMES
 _ JAVADOC_AUTOBRIEF
 _ QT_AUTOBRIEF
 _ MULTILINE_CPP_IS_BRIEF
 _ DETAILS_AT_TOP
 x INHERIT_DOCS
 _ SEPARATE_MEMBER_PAGES
   TAB_SIZE  8
   ALIASES		left blank

 x OPTIMIZE_OUTPUT_FOR_C
 _ OPTIMIZE_OUTPUT_FOR_JAVA
 _ BUILTIN_STL_SUPPORT
 _ CPP_CLI_SUPPORT
 _ DISTRIBUTE_GROUP_DOC


Build: -------------------------------
 _ EXTRACT_ALL		
 x EXTRACT_PRIVATE	
 x EXTRACT_STATIC
 x EXTRACT_LOCAL_CLASSES
 _ EXTRACT_LOCAL_METHODS
 _ EXTRACT__ANON_NSPACES
 _ HIDE_UNDOC_MEMBERS
 x HIDE_UNDOC_CLASSES
 _ HIDE_FRIEND_COMPOUNDS
 _ HIDE_IN_BODY_DOCS
 _ INTERNAL_DOCS
 _ CASE_SENSE_NAMES
 _ HIDE_SCOPE_NAMES
 x SHOW_INCLUDE_FILES
 x INLINE_INFO
 _ SORT_MEMBER_DOCS
 _ SORT_BRIEF_DOCS

Messages -------------------------------
left these settings at defaults

Inputs ---------------------------------
The INPUT area was my 1st encounter with their unusual list editor.
You can add a line to the following large box by typing it into the
'INPUT' window and hitting '+'. You can remove a line by highlighting
it and hitting '-'.  I imagine 'Select' is a file browser.

    C:/$Prj/Src
    C:/$Prj/Src/Tags/ST_654_ASIC
    C:/$Prj/Src/Tags/ST_654_ASIC/coder

   INPUT_ENCODING:  UTF-8	(default)

   FILE_PATTERNS:  I removed the C++ entries etc to get '.c', '.h'

 _ RECURSIVE    guess I should have tried this ...


   EXCLUDE:    left blank

 _ EXCLUDE_SYMLINKS    left blank

   EXCLUDE_PATTERNS    left blank

Source Browser ---------------------------
left at defaults

Index ------------------------------------
left at defaults

Html -------------------------------------
Note that you can provide a .css (Cascading Style Sheet) on this
page.

 x GENERATE_HTML     default. left page at defaults.

   HTML_OUTPUT		html
   HTML_FILE_EXTENSION .html
   HTML_HEADER		left blank
   HTML_FOOTER		left blank
   HTML_STYLESHEET	left blank


Latex ------------------------------------

 _ GENERATE_LATEX    disabled this.


Dot --------------------------------------
 _ CLASS_DIAGRAMS   think i deselected this. some files had troubles...
   MSCGEN_PATH      ?path to app which makes diagrams (?)
 x HIDE_UNDOC_RELATIONS
 _ HAVE_DOT
   rest of the entries were grayed, presumably cuz we didn't have "DOT".

Rest of the tabs: didn't change anything...




The wizard does more than build the config file. Its last button,
"Start", also runs Doxygen to make the output files.

Editing text files to support Doxygen
-------------------------------------
code, how to format comments so doxygen uses them 
/** starts special block
*/	ends it

\ starts a command to doxygen
\brief
\class, \struct, \union, \enum, \fn, \var, 
\def for a #define, \typedef, \file, \package, 
\param	like to doc the params to a macro
\bug		makes a bug list !
\todo		enters it into a Todo List !

'07 note: now see '@' used to start commands like @param ...

/// works. but hafta have 2+ lines of this sort.
/// and when done, the code for this lies BELOW the
/// comments.

blah=0; //< whereas this comment goes w/ code on same line

/**\brief  says a paragraph sized 'brief description' follows
 * until broken by an empty line
 * like the following
 *
 * this would then be the full description
 */

}

Iterating on the documentation you're adding
--------------------------------------------
Make up a config file as discussed above and make a copy of the
file. Using a text editor on the copy, find the section entitled 
INPUT and change its value to be a simple list of files you want 
feedback on.   
INPUT = path1/one.c path1/two.c \
        path2/one.c

You probably want to also redefine the output directory.

Then select this config by name and Start Doxygen on it.
When it finishes, hit the "Save Log File" and read it.
When your new output directory is made, wander into the
html subdirectory, make a shortcut for index.html and drag
that shortcut to your desktop for faster access.




CONFIG'g manually   {  ----------------------------------
You _can_ edit the config file yourself. here's what it looks like:
tagword ~ value(s)

;; CLASS_DIAGRAMS ~ YES   yes is the default. outs in html. "use dot"
WARNINGS ~ YES
WARN_IF_UNDOCUMENTED ~ YES
WARN_NO_PARAMDOC
HAVE_DOT   ~	YES
FILE_PATTERNS *.c *.cc *.h *.asm *.pic etc
INPUT 
CLASS_GRAPH


file: dox_howto.html,