add documentation of the logging interface

doc/CMakeLists.txt

@@ -16,6 +16,7 @@ generate_rst(${PROJECT_SOURCE_DIR}/include/ua_constants.h ${PROJECT_BINARY_DIR}/
 generate_rst(${PROJECT_BINARY_DIR}/src_generated/ua_types_generated.h ${PROJECT_BINARY_DIR}/doc_src/types_generated.rst)
 generate_rst(${PROJECT_SOURCE_DIR}/include/ua_server.h ${PROJECT_BINARY_DIR}/doc_src/server.rst)
 generate_rst(${PROJECT_SOURCE_DIR}/include/ua_client.h ${PROJECT_BINARY_DIR}/doc_src/client.rst)
+generate_rst(${PROJECT_SOURCE_DIR}/include/ua_log.h ${PROJECT_BINARY_DIR}/doc_src/log.rst)
 generate_rst(${PROJECT_SOURCE_DIR}/src/server/ua_services.h ${PROJECT_BINARY_DIR}/doc_src/services.rst)
 generate_rst(${PROJECT_SOURCE_DIR}/src/server/ua_nodestore.h ${PROJECT_BINARY_DIR}/doc_src/nodestore.rst)
 
@@ -26,6 +27,7 @@ add_custom_target(doc_latex ${SPHINX_EXECUTABLE}
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/types_generated.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/server.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/client.rst
+  DEPENDS ${PROJECT_BINARY_DIR}/doc_src/log.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/services.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/nodestore.rst
   COMMENT "Building LaTeX sources for documentation with Sphinx")
@@ -39,6 +41,7 @@ add_custom_target(doc ${SPHINX_EXECUTABLE}
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/types_generated.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/server.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/client.rst
+  DEPENDS ${PROJECT_BINARY_DIR}/doc_src/log.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/services.rst
   DEPENDS ${PROJECT_BINARY_DIR}/doc_src/nodestore.rst
   COMMENT "Building HTML documentation with Sphinx")

doc/internal.rst

@@ -5,3 +5,4 @@ Internals
    services
    nodestore
    types_generated
+   log

include/ua_log.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 the contributors as stated in the AUTHORS file
+ * Copyright (C) 2014-2016 the contributors as stated in the AUTHORS file
  *
  * This file is part of open62541. open62541 is free software: you can
  * redistribute it and/or modify it under the terms of the GNU Lesser General
@@ -23,11 +23,11 @@ extern "C" {
 #include "ua_config.h"
 
 /**
- * @defgroup logging Logging
- *
- * @brief Custom logging solutions can be "plugged in" with this interface
- *
- * @{
+ * Logging
+ * -------
+ * Servers and clients may contain a logger. Every logger needs to implement the
+ * `UA_Logger` signature. An example logger that writes to stdout is provided in
+ * the plugins folder.
  */
 
 typedef enum {
@@ -48,6 +48,10 @@ typedef enum {
     UA_LOGCATEGORY_USERLAND
 } UA_LogCategory;
     
+/* The signature of the logger. The msg string and following varargs are used to
+   include variable data similar to printf. Do not use the logger directly but
+   make use of the following macros that take the minimum log-level defined in
+   ua_config.h into account. */
 typedef void (*UA_Logger)(UA_LogLevel level, UA_LogCategory category, const char *msg, ...);
 
 #if UA_LOGLEVEL <= 100
@@ -92,8 +96,6 @@ typedef void (*UA_Logger)(UA_LogLevel level, UA_LogCategory category, const char
 #define UA_LOG_FATAL(LOGGER, CATEGORY, ...) do {} while(0)
 #endif
 
-/** @} */
-
 #ifdef __cplusplus
 } // extern "C"
 #endif