docs: Add all API documentation

Also fix a few inconsistencies in the code.

Author: xlz

Doxyextra.css

@@ -0,0 +1,36 @@
+@import url(https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Mono:400);
+
+body, table, div, p, dl, table.directory, div.toc li, div.toc h3, div.summary, div.ingroups, .tabsearch, .directory .levels, span.mlabel {
+  font: 400 18px/24px Lato,sans-serif;
+}
+.title, .icon, .navpath li.navelem a, #projectname, #projectbrief, #projectnumber, #powerTip div, .tabs, .tabs2, .tabs3 {
+  font-family: Lato,sans-serif;
+}
+
+#projectname {
+  font-weight: bold;
+}
+
+.icon {
+  height: 100%;
+}
+.title {
+  font-size: 200%;
+}
+
+code {
+  font: 400 16px/20px Roboto Mono,monospace;
+}
+pre.fragment, div.line, .params .paramdir {
+  font-family: Roboto Mono,monospace;
+}
+
+p, li {
+  max-width: 50em;
+}
+
+div.contents, #titlearea, div.header, div.navpath ul, .tabs, .tabs2, .tabs3 {
+  padding-left: 5em;
+  padding-right: 5em;
+}
+

Doxyfile.in

@@ -38,7 +38,7 @@ PROJECT_NAME           = @PROJECT_NAME@
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         =
+PROJECT_NUMBER         = @PROJECT_VERSION@
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -144,7 +144,7 @@ FULL_PATH_NAMES        = YES
 # will be relative from the directory where doxygen is started.
 # This tag requires that the tag FULL_PATH_NAMES is set to YES.
 
-STRIP_FROM_PATH        = .
+STRIP_FROM_PATH        = @CMAKE_SOURCE_DIR@
 
 # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the
 # path mentioned in the documentation of a class, which tells the reader which
@@ -153,7 +153,7 @@ STRIP_FROM_PATH        = .
 # specify the list of include paths that are normally passed to the compiler
 # using the -I flag.
 
-STRIP_FROM_INC_PATH    = .
+STRIP_FROM_INC_PATH    = @CMAKE_SOURCE_DIR@/include
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter (but
 # less readable) file names. This can be useful is your file systems doesn't
@@ -169,7 +169,7 @@ SHORT_NAMES            = NO
 # description.)
 # The default value is: NO.
 
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
 
 # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first
 # line (until the first dot) of a Qt-style comment as the brief description. If
@@ -404,13 +404,13 @@ EXTRACT_ALL            = YES
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = YES
+EXTRACT_PRIVATE        = NO
 
 # If the EXTRACT_PACKAGE tag is set to YES all members with package or internal
 # scope will be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PACKAGE        = YES
+EXTRACT_PACKAGE        = NO
 
 # If the EXTRACT_STATIC tag is set to YES all static members of a file will be
 # included in the documentation.
@@ -494,7 +494,7 @@ CASE_SENSE_NAMES       = YES
 # scope will be hidden.
 # The default value is: NO.
 
-HIDE_SCOPE_NAMES       = NO
+HIDE_SCOPE_NAMES       = YES
 
 # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of
 # the files that are included by a file in the documentation of that file.
@@ -526,7 +526,7 @@ INLINE_INFO            = YES
 # name. If set to NO the members will appear in declaration order.
 # The default value is: YES.
 
-SORT_MEMBER_DOCS       = YES
+SORT_MEMBER_DOCS       = NO
 
 # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief
 # descriptions of file, namespace and class members alphabetically by member
@@ -546,14 +546,14 @@ SORT_BRIEF_DOCS        = NO
 # detailed member documentation.
 # The default value is: NO.
 
-SORT_MEMBERS_CTORS_1ST = NO
+SORT_MEMBERS_CTORS_1ST = YES
 
 # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy
 # of group names into alphabetical order. If set to NO the group names will
 # appear in their defined order.
 # The default value is: NO.
 
-SORT_GROUP_NAMES       = NO
+SORT_GROUP_NAMES       = YES
 
 # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be sorted by
 # fully-qualified names, including namespaces. If set to NO, the class list will
@@ -624,7 +624,7 @@ MAX_INITIALIZER_LINES  = 30
 # will mention the files that were used to generate the documentation.
 # The default value is: YES.
 
-SHOW_USED_FILES        = YES
+SHOW_USED_FILES        = NO
 
 # Set the SHOW_FILES tag to NO to disable the generation of the Files page. This
 # will remove the Files entry from the Quick Index and from the Folder Tree View
@@ -638,7 +638,7 @@ SHOW_FILES             = YES
 # Folder Tree View (if specified).
 # The default value is: YES.
 
-SHOW_NAMESPACES        = YES
+SHOW_NAMESPACES        = NO
 
 # The FILE_VERSION_FILTER tag can be used to specify a program or script that
 # doxygen should invoke to get the current version for each file (typically from
@@ -811,7 +811,7 @@ EXCLUDE_SYMBOLS        =
 # that contain example code fragments that are included (see the \include
 # command).
 
-EXAMPLE_PATH           =
+EXAMPLE_PATH           = @CMAKE_SOURCE_DIR@/examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and
@@ -892,7 +892,7 @@ USE_MDFILE_AS_MAINPAGE =
 # also VERBATIM_HEADERS is set to NO.
 # The default value is: NO.
 
-SOURCE_BROWSER         = YES
+SOURCE_BROWSER         = NO
 
 # Setting the INLINE_SOURCES tag to YES will include the body of functions,
 # classes and enums directly into the documentation.
@@ -965,7 +965,7 @@ USE_HTAGS              = NO
 # See also: Section \class.
 # The default value is: YES.
 
-VERBATIM_HEADERS       = YES
+VERBATIM_HEADERS       = NO
 
 #---------------------------------------------------------------------------
 # Configuration options related to the alphabetical class index
@@ -976,7 +976,7 @@ VERBATIM_HEADERS       = YES
 # classes, structs, unions or interfaces.
 # The default value is: YES.
 
-ALPHABETICAL_INDEX     = YES
+ALPHABETICAL_INDEX     = NO
 
 # The COLS_IN_ALPHA_INDEX tag can be used to specify the number of columns in
 # which the alphabetical index list will be split.
@@ -1068,7 +1068,7 @@ HTML_STYLESHEET        =
 # see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_STYLESHEET  = @CMAKE_SOURCE_DIR@/Doxyextra.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -1466,7 +1466,7 @@ MATHJAX_CODEFILE       =
 # The default value is: YES.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-SEARCHENGINE           = YES
+SEARCHENGINE           = NO
 
 # When the SERVER_BASED_SEARCH tag is enabled the search engine will be
 # implemented using a web server instead of a web client using Javascript. There
@@ -1883,15 +1883,15 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
 # EXPAND_AS_DEFINED tags.
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES the includes files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -1923,7 +1923,7 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = LIBFREENECT2_API
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

examples/Protonect.cpp

@@ -29,11 +29,13 @@
 #include <iostream>
 #include <signal.h>
 
+/// [headers]
 #include <libfreenect2/libfreenect2.hpp>
 #include <libfreenect2/frame_listener_impl.h>
 #include <libfreenect2/registration.h>
 #include <libfreenect2/packet_pipeline.h>
 #include <libfreenect2/logger.h>
+/// [headers]
 #ifdef EXAMPLES_WITH_OPENGL_SUPPORT
 #include "viewer.h"
 #endif
@@ -47,6 +49,7 @@ void sigint_handler(int s)
 }
 
 //The following demostrates how to create a custom logger
+/// [logger]
 #include <fstream>
 #include <cstdlib>
 class MyFileLogger: public libfreenect2::Logger
@@ -69,7 +72,9 @@ class MyFileLogger: public libfreenect2::Logger
     logfile_ << "[" << libfreenect2::Logger::level2str(level) << "] " << message << std::endl;
   }
 };
+/// [logger]
 
+/// [main]
 /**
  * Main application entry point.
  *
@@ -81,6 +86,7 @@ class MyFileLogger: public libfreenect2::Logger
  * - -noviewer Disable viewer window.
  */
 int main(int argc, char *argv[])
+/// [main]
 {
   std::string program_path(argv[0]);
   std::cerr << "Environment variables: LOGFILE=<protonect.log>" << std::endl;
@@ -94,28 +100,36 @@ int main(int argc, char *argv[])
     binpath = program_path.substr(0, executable_name_idx);
   }
 
-  libfreenect2::Freenect2 freenect2;
 #if defined(WIN32) || defined(_WIN32) || defined(__WIN32__)
   // avoid flooing the very slow Windows console with debug messages
   libfreenect2::setGlobalLogger(libfreenect2::createConsoleLogger(libfreenect2::Logger::Info));
 #else
   // create a console logger with debug level (default is console logger with info level)
+/// [logging]
   libfreenect2::setGlobalLogger(libfreenect2::createConsoleLogger(libfreenect2::Logger::Debug));
+/// [logging]
 #endif
+/// [file logging]
   MyFileLogger *filelogger = new MyFileLogger(getenv("LOGFILE"));
   if (filelogger->good())
     libfreenect2::setGlobalLogger(filelogger);
+/// [file logging]
 
+/// [context]
+  libfreenect2::Freenect2 freenect2;
   libfreenect2::Freenect2Device *dev = 0;
   libfreenect2::PacketPipeline *pipeline = 0;
+/// [context]
 
+/// [discovery]
   if(freenect2.enumerateDevices() == 0)
   {
     std::cout << "no device connected!" << std::endl;
     return -1;
   }
 
   std::string serial = freenect2.getDefaultDeviceSerialNumber();
+/// [discovery]
 
   bool viewer_enabled = true;
 
@@ -126,7 +140,9 @@ int main(int argc, char *argv[])
     if(arg == "cpu")
     {
       if(!pipeline)
+/// [pipeline]
         pipeline = new libfreenect2::CpuPacketPipeline();
+/// [pipeline]
     }
     else if(arg == "gl")
     {
@@ -162,7 +178,9 @@ int main(int argc, char *argv[])
 
   if(pipeline)
   {
+/// [open]
     dev = freenect2.openDevice(serial, pipeline);
+/// [open]
   }
   else
   {
@@ -178,18 +196,25 @@ int main(int argc, char *argv[])
   signal(SIGINT,sigint_handler);
   protonect_shutdown = false;
 
+/// [listeners]
   libfreenect2::SyncMultiFrameListener listener(libfreenect2::Frame::Color | libfreenect2::Frame::Ir | libfreenect2::Frame::Depth);
   libfreenect2::FrameMap frames;
-  libfreenect2::Frame undistorted(512, 424, 4), registered(512, 424, 4);
 
   dev->setColorFrameListener(&listener);
   dev->setIrAndDepthFrameListener(&listener);
+/// [listeners]
+
+/// [start]
   dev->start();
 
   std::cout << "device serial: " << dev->getSerialNumber() << std::endl;
   std::cout << "device firmware: " << dev->getFirmwareVersion() << std::endl;
+/// [start]
 
+/// [registration setup]
   libfreenect2::Registration* registration = new libfreenect2::Registration(dev->getIrCameraParams(), dev->getColorCameraParams());
+  libfreenect2::Frame undistorted(512, 424, 4), registered(512, 424, 4);
+/// [registration setup]
 
   size_t framecount = 0;
 #ifdef EXAMPLES_WITH_OPENGL_SUPPORT
@@ -200,14 +225,18 @@ int main(int argc, char *argv[])
   viewer_enabled = false;
 #endif
 
+/// [loop start]
   while(!protonect_shutdown)
   {
     listener.waitForNewFrame(frames);
     libfreenect2::Frame *rgb = frames[libfreenect2::Frame::Color];
     libfreenect2::Frame *ir = frames[libfreenect2::Frame::Ir];
     libfreenect2::Frame *depth = frames[libfreenect2::Frame::Depth];
+/// [loop start]
 
+/// [registration]
     registration->apply(rgb, depth, &undistorted, &registered);
+/// [registration]
 
     framecount++;
     if (!viewer_enabled)
@@ -227,14 +256,18 @@ int main(int argc, char *argv[])
     protonect_shutdown = protonect_shutdown || viewer.render();
 #endif
 
+/// [loop end]
     listener.release(frames);
-    //libfreenect2::this_thread::sleep_for(libfreenect2::chrono::milliseconds(100));
+    /** libfreenect2::this_thread::sleep_for(libfreenect2::chrono::milliseconds(100)); */
   }
+/// [loop end]
 
   // TODO: restarting ir stream doesn't work!
   // TODO: bad things will happen, if frame listeners are freed before dev->stop() :(
+/// [stop]
   dev->stop();
   dev->close();
+/// [stop]
 
   delete registration;