Merge pull request #380 from alberth/add_doxydocs

Add: Doxygen documentation comment for many of the classes.

Author: floe

Doxyfile

@@ -24,6 +24,7 @@
  * either License.
  */
 
+/** @file Protonect.cpp Main application file. */
 
 #include <iostream>
 #include <signal.h>
@@ -39,7 +40,7 @@
 #endif
 
 
-bool protonect_shutdown = false;
+bool protonect_shutdown = false; ///< Whether the running application should shut down.
 
 void sigint_handler(int s)
 {
@@ -69,6 +70,16 @@ class MyFileLogger: public libfreenect2::Logger
   }
 };
 
+/**
+ * Main application entry point.
+ *
+ * Accepted argumemnts:
+ * - cpu Perform depth processing with the CPU.
+ * - gl  Perform depth processing with OpenGL.
+ * - cl  Perform depth processing with OpenCL.
+ * - <number> Serial number of the device to open.
+ * - -noviewer Disable viewer window.
+ */
 int main(int argc, char *argv[])
 {
   std::string program_path(argv[0]);

examples/protonect/Protonect.cpp

@@ -24,6 +24,8 @@
  * either License.
  */
 
+/** @file async_packet_processor.h Asynchronous processing of packets. */
+
 #ifndef ASYNC_PACKET_PROCESSOR_H_
 #define ASYNC_PACKET_PROCESSOR_H_
 
@@ -33,19 +35,28 @@
 namespace libfreenect2
 {
 
+/**
+ * Packet processor that runs asynchronously.
+ * @tparam PacketT Type of the packet being processed.
+ */
 template<typename PacketT>
 class AsyncPacketProcessor : public PacketProcessor<PacketT>
 {
 public:
   typedef PacketProcessor<PacketT>* PacketProcessorPtr;
 
+  /**
+   * Constructor.
+   * @param processor Object performing the processing.
+   */
   AsyncPacketProcessor(PacketProcessorPtr processor) :
     processor_(processor),
     current_packet_available_(false),
     shutdown_(false),
     thread_(&AsyncPacketProcessor<PacketT>::static_execute, this)
   {
   }
+
   virtual ~AsyncPacketProcessor()
   {
     shutdown_ = true;
@@ -77,20 +88,25 @@ class AsyncPacketProcessor : public PacketProcessor<PacketT>
     packet_condition_.notify_one();
   }
 private:
-  PacketProcessorPtr processor_;
-  bool current_packet_available_;
-  PacketT current_packet_;
+  PacketProcessorPtr processor_;  ///< The processing routine, executed in the asynchronous thread.
+  bool current_packet_available_; ///< Whether #current_packet_ still needs processing.
+  PacketT current_packet_;        ///< Packet being processed.
 
   bool shutdown_;
-  libfreenect2::mutex packet_mutex_;
-  libfreenect2::condition_variable packet_condition_;
-  libfreenect2::thread thread_;
-
+  libfreenect2::mutex packet_mutex_; ///< Mutex indicating a new packet can be stored in #current_packet_.
+  libfreenect2::condition_variable packet_condition_; ///< Mutex indicating processing is blocked on lack of packets.
+  libfreenect2::thread thread_; ///< Asynchronous thread.
+
+  /**
+   * Wrapper function to start the thread.
+   * @param data The #AsyncPacketProcessor object to use.
+   */
   static void static_execute(void *data)
   {
     static_cast<AsyncPacketProcessor<PacketT> *>(data)->execute();
   }
 
+  /** Asynchronously process a provided packet. */
   void execute()
   {
     libfreenect2::unique_lock l(packet_mutex_);

examples/protonect/include/libfreenect2/async_packet_processor.h

@@ -23,8 +23,9 @@
  * Binary distributions must follow the binary distribution requirements of
  * either License.
  */
- 
- 
+
+/** @file data_callback.h Callback interface on arrival of new data. */
+
 #ifndef DATA_CALLBACK_H_
 #define DATA_CALLBACK_H_
 
@@ -37,6 +38,11 @@ namespace libfreenect2
 class LIBFREENECT2_API DataCallback
 {
 public:
+  /**
+   * Callback that new data has arrived.
+   * @param buffer Buffer with new data.
+   * @param n Size of the new data.
+   */
   virtual void onDataReceived(unsigned char *buffer, size_t n) = 0;
 };
 

examples/protonect/include/libfreenect2/data_callback.h

@@ -24,6 +24,8 @@
  * either License.
  */
 
+/** @file depth_packet_processor.h Depth processor definitions. */
+
 #ifndef DEPTH_PACKET_PROCESSOR_H_
 #define DEPTH_PACKET_PROCESSOR_H_
 
@@ -37,30 +39,34 @@
 namespace libfreenect2
 {
 
+/** Data packet with depth information. */
 struct LIBFREENECT2_API DepthPacket
 {
   uint32_t sequence;
   uint32_t timestamp;
-  unsigned char *buffer;
-  size_t buffer_length;
+  unsigned char *buffer; ///< Depth data.
+  size_t buffer_length;  ///< Size of depth data.
 };
 
+/** Class for processing depth information. */
 typedef PacketProcessor<DepthPacket> BaseDepthPacketProcessor;
 
 class LIBFREENECT2_API DepthPacketProcessor : public BaseDepthPacketProcessor
 {
 public:
+  /** Configuration of depth processing. */
   struct LIBFREENECT2_API Config
   {
     float MinDepth;
     float MaxDepth;
-    
-    bool EnableBilateralFilter;
-    bool EnableEdgeAwareFilter;
-    
+
+    bool EnableBilateralFilter; ///< Whether to run the bilateral filter.
+    bool EnableEdgeAwareFilter; ///< Whether to run the edge aware filter.
+
     Config();
   };
 
+  /** Parameters of depth processing. */
   struct LIBFREENECT2_API Parameters
   {
     float ab_multiplier;
@@ -112,6 +118,7 @@ class LIBFREENECT2_API DepthPacketProcessor : public BaseDepthPacketProcessor
 #ifdef LIBFREENECT2_WITH_OPENGL_SUPPORT
 class OpenGLDepthPacketProcessorImpl;
 
+/** Depth packet processor using OpenGL. */
 class LIBFREENECT2_API OpenGLDepthPacketProcessor : public DepthPacketProcessor
 {
 public:
@@ -142,6 +149,7 @@ class LIBFREENECT2_API OpenGLDepthPacketProcessor : public DepthPacketProcessor
 // TODO: push this to some internal namespace
 class CpuDepthPacketProcessorImpl;
 
+/** Depth packet processor using the CPU. */
 class LIBFREENECT2_API CpuDepthPacketProcessor : public DepthPacketProcessor
 {
 public:
@@ -171,6 +179,7 @@ class LIBFREENECT2_API CpuDepthPacketProcessor : public DepthPacketProcessor
 #ifdef LIBFREENECT2_WITH_OPENCL_SUPPORT
 class OpenCLDepthPacketProcessorImpl;
 
+/** Depth packet processor using OpenCL. */
 class LIBFREENECT2_API OpenCLDepthPacketProcessor : public DepthPacketProcessor
 {
 public:

examples/protonect/include/libfreenect2/depth_packet_processor.h

@@ -24,6 +24,8 @@
  * either License.
  */
 
+/** @file depth_packet_stream_parser.h Parser processor definitions of depth packets. */
+
 #ifndef DEPTH_PACKET_STREAM_PARSER_H_
 #define DEPTH_PACKET_STREAM_PARSER_H_
 
@@ -40,6 +42,7 @@
 namespace libfreenect2
 {
 
+/** Footer of a depth packet. */
 LIBFREENECT2_PACK(struct LIBFREENECT2_API DepthSubPacketFooter
 {
   uint32_t magic0;
@@ -51,6 +54,10 @@ LIBFREENECT2_PACK(struct LIBFREENECT2_API DepthSubPacketFooter
   uint32_t fields[32];
 });
 
+/**
+ * Parser of th depth stream, recognizes valid depth packets in the stream, and
+ * passes them on for further processing.
+ */
 class LIBFREENECT2_API DepthPacketStreamParser : public DataCallback
 {
 public:

examples/protonect/include/libfreenect2/depth_packet_stream_parser.h

@@ -24,6 +24,8 @@
  * either License.
  */
 
+/** @file double_buffer.h Double buffer implementation. */
+
 #ifndef DOUBLE_BUFFER_H_
 #define DOUBLE_BUFFER_H_
 
@@ -33,14 +35,16 @@
 namespace libfreenect2
 {
 
+/** Data of a single buffer. */
 struct LIBFREENECT2_API Buffer
 {
 public:
-  size_t capacity;
-  size_t length;
-  unsigned char* data;
+  size_t capacity; ///< Capacity of the buffer.
+  size_t length;   ///< Used length of the buffer.
+  unsigned char* data; ///< Start address of the buffer.
 };
 
+/** Double bufffer class. */
 class LIBFREENECT2_API DoubleBuffer
 {
 public:
@@ -55,10 +59,10 @@ class LIBFREENECT2_API DoubleBuffer
 
   Buffer& back();
 private:
-  Buffer buffer_[2];
-  unsigned char front_buffer_index_;
+  Buffer buffer_[2]; // Both data buffers.
+  unsigned char front_buffer_index_; ///< Index of the front buffer.
 
-  unsigned char* buffer_data_;
+  unsigned char* buffer_data_; ///< Memory holding both buffers.
 };
 
 } /* namespace libfreenect2 */

examples/protonect/include/libfreenect2/double_buffer.h

@@ -24,6 +24,8 @@
  * either License.
  */
 
+/** @file frame_listener.hpp Classes for frame listeners. */
+
 #ifndef FRAME_LISTENER_HPP_
 #define FRAME_LISTENER_HPP_
 
@@ -34,20 +36,24 @@
 namespace libfreenect2
 {
 
+/** A frame from the stream. */
 class LIBFREENECT2_API Frame
 {
   public:
+  /** Available types of frames. */
   enum Type
   {
-    Color = 1,
-    Ir = 2,
-    Depth = 4
+    Color = 1, ///< RGB frame.
+    Ir = 2,    ///< IR frame.
+    Depth = 4  ///< Depth frame.
   };
 
   uint32_t timestamp;
   uint32_t sequence;
-  size_t width, height, bytes_per_pixel;
-  unsigned char* data;
+  size_t width;           ///< Length of a line (in pixels).
+  size_t height;          ///< Number of lines in the frame.
+  size_t bytes_per_pixel; ///< Number of bytes in a pixel.
+  unsigned char* data;    ///< Data of the frame (aligned).
 
   Frame(size_t width, size_t height, size_t bytes_per_pixel) :
     width(width),
@@ -68,14 +74,20 @@ class LIBFREENECT2_API Frame
   }
 
   protected:
-  unsigned char* rawdata;
+  unsigned char* rawdata; ///< Unaligned start of #data.
 };
 
+/** Callback class for waiting on a new frame. */
 class LIBFREENECT2_API FrameListener
 {
 public:
   virtual ~FrameListener();
 
+  /**
+   * A new frame has arrived, process it.
+   * @param type Type of the new frame.
+   * @param frame Data of the frame.
+   */
   virtual bool onNewFrame(Frame::Type type, Frame *frame) = 0;
 };
 

examples/protonect/include/libfreenect2/frame_listener.hpp

@@ -24,6 +24,8 @@
  * either License.
  */
 
+/** @file frame_listener_impl.h Implementation of the frame listener classes. */
+
 #ifndef FRAME_LISTENER_IMPL_H_
 #define FRAME_LISTENER_IMPL_H_
 
@@ -35,10 +37,12 @@
 namespace libfreenect2
 {
 
+/** Storage of frames by type. */
 typedef std::map<Frame::Type, Frame*> FrameMap;
 
 class SyncMultiFrameListenerImpl;
 
+/** Class for collecting and combining frames from different sources. */
 class LIBFREENECT2_API SyncMultiFrameListener : public FrameListener
 {
 public: