From 70e5dd5705d063119c2c0757082fd3a82c53ee71 Mon Sep 17 00:00:00 2001
From: Matthias Vogelgesang <matthias.vogelgesang@kit.edu>
Date: Fri, 3 Feb 2012 11:58:43 +0100
Subject: Document recent changes

---
 doc/CMakeLists.txt |  7 ++++---
 src/uca.h          | 14 +++++++++++---
 2 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index ff2030a..0e5afd1 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -7,10 +7,11 @@ if(DOXYGEN_FOUND)
     configure_file(${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
     configure_file(${CMAKE_CURRENT_SOURCE_DIR}/publish.sh.in ${CMAKE_CURRENT_BINARY_DIR}/publish.sh)
 
-    # add 'ALL after 'doc' to create documentation, whenever you type make
-    add_custom_target(doc
-        ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
+    add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/html/index.html
+        COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
         WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/../src/uca.h
         COMMENT "Generating API documentation with Doxygen" VERBATIM
         )
+    add_custom_target(docs ALL DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/html/index.html)
 endif(DOXYGEN_FOUND)
diff --git a/src/uca.h b/src/uca.h
index 6721e58..1df870f 100644
--- a/src/uca.h
+++ b/src/uca.h
@@ -208,6 +208,8 @@ enum uca_access_rights {
 
 /**
  * Describes the current state of the camera.
+ *
+ * \see uca_cam_get_state()
  */
 enum uca_cam_state {
     UCA_CAM_CONFIGURABLE,   /**< Camera can be configured and is not recording */
@@ -220,16 +222,19 @@ enum uca_cam_state {
  * Specify if the callback function keeps the buffer and will call
  * ufo_cam_release_buffer() at later time or if after returning the buffer can
  * be released automatically.
+ *
+ * \since 0.5
  */
 enum uca_buffer_status {
-    UCA_BUFFER_KEEP,
-    UCA_BUFFER_RELEASE
+    UCA_BUFFER_KEEP,        /**< Keep the buffer and call ufo_cam_release_buffer() manually */
+    UCA_BUFFER_RELEASE      /**< Buffer is released upon return */
 };
 
 /**
  * A uca_property_t describes a vendor-independent property used by cameras and
  * frame grabbers. It basically consists of a human-readable name, a physical
  * unit, a type and some access rights.
+ * \see uca_get_full_property()
  */
 typedef struct uca_property {
     /**
@@ -266,6 +271,9 @@ union uca_value {
  * \param[in] meta_data Meta data provided by the camera specifying per-frame
  *   data.
  * \param[in] user User data registered in uca_cam_register_callback()
+ * \return Value from uca_buffer_status. If #UCA_BUFFER_KEEP is returned, the
+ * callee must make sure to call uca_cam_release_buffer(). On the other hand, if
+ * #UCA_BUFFER_RELEASE is returned this is done by the caller.
  *
  * \note The meta data parameter is not yet specified but just a place holder.
  */
@@ -357,7 +365,7 @@ typedef struct uca {
  *   relying on external calibration data. It is ignored when no JSON parser can
  *   be found at compile time or config_filename is NULL.
  *
- * \return Pointer to a uca structure
+ * \return Pointer to a #uca structure
  *
  * \note uca_init() is thread-safe if a Pthread-implementation is available.
  */
-- 
cgit v1.2.3