Doxygen is the standard tool for generating documentation from annotated C++ sources. You can download it from its downloads page.
- It can generate an on-line documentation browser (in HTML) and/or an off-line reference manual (in LaTeX) from a set of documented source files. There is also support for generating output in RTF (MS-Word), PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. The documentation is extracted directly from the sources, which makes it much easier to keep the documentation consistent with the source code.
- You can configure doxygen to extract the code structure from undocumented source files. This is very useful to quickly find your way in large source distributions. Doxygen can also visualize the relations between the various elements by means of include dependency graphs, inheritance diagrams, and collaboration diagrams, which are all generated automatically.
~$ cd /blocks/[USER]/[BLOCK]
~/blocks/[USER]/[BLOCK]$ mkdir docs
~/blocks/[USER]/[BLOCK]$ cd docs
~/blocks/[USER]/[BLOCK]/docs$ doxygen -g
The minimal info that you need to change in your Doxyfile is the following tags:
PROJECT_NAME = "My Project"
OUTPUT_DIRECTORY = .
INPUT = ../
FILE_PATTERNS = *.c \
*.cc \
*.cxx \
*.cpp \
*.c++ \
*.h \
*.hh \
*.hxx \
*.hpp \
*.h++ \
~/docs$ doxygen Doxyfile
#Open the /docs/html/index.html with your web browser.
All the info of the previous examples have been written taking as reference a docs
folder inside your block
.
However, you can create your Doxyfile where you want changing the INPUT tag in your Doxyfile.
For example, to generate the docs folder in you project
, you need to specify: INPUT = ../blocks/[USER]/[BLOCK_NAME]/
.
Read more info about doxygen in the official documentation.
If you want to make your own main page, you can create a DoxygenMainpage.h
in the docs folder with the following sections:
/**
@mainpage TITLE_OF_YOUR_HOME_PAGE
@author YOUR_USER_NAME and all the info about the author
Description of you block
@section TITLE
Section info
*/
A good example is libfreenect/doc/DoxygenMainpage.h:
/**
@mainpage libfreenect
@author The OpenKinect Community - http://www.github.com/openkinect
Cross-platform driver for the Microsoft Kinect Camera
Website: http://www.openkinect.org
@section libfreenectIntro Introduction
libfreenect is an open source, cross platform development library for
the Microsoft Kinect camera. It provides basic functionality to
connect to the camera, set configuration values, retrieve (and in some
cases decompress) images, and provides functionalty for the LED and
Motor.
@section libfreenectDesignOverview Design Overview
libfreenect provides access to devices via two structs:
- A context, which manages aspects of thread safety when using
multiple devices on multiple threads.
- A device, which talks to the hardware and manages transfers and configuration.
Either or both of these structs are passed to the functions in order
to interact with the hardware. The USB access is handled by
libusb-1.0, which should work in a mostly non-blocking fashion across
all platforms (see function documentation for specifics).
@section libfreenectShouldIUseIt Should You Use libfreenect?
The main design goal of libfreenect is to provide a simple, usable
reference implementation of the Kinect USB protocol for access via
non-Xbox hardware. With this in mind, the library does not contain any
algorithms relevant to computer vision usages of the camera.
If you are looking for machine vision algorithms, we recommend the
OpenCV library, available at
http://www.opencv.org
If you are looking to use the kinect in a larger framework that may
involve other depth sensors, we recommend the OpenNI framework,
available at
http://www.openni.org
Note that libfreenect can be used as a hardware node in OpenNI.
*/