Fixed desription of logging library

diff --git a/components/log/README.rst b/components/log/README.rst
new file mode 100644 (file)
index 0000000..d378179
--- /dev/null
+++ b/components/log/README.rst
@@ -0,0 +1,61 @@
+Logging library
+===============
+
+Overview
+--------
+
+Log library has two ways of managing log verbosity: compile time, set via menuconfig; and runtime, using ``esp_log_set_level`` function.
+
+At compile time, filtering is done using ``CONFIG_LOG_DEFAULT_LEVEL`` macro, set via menuconfig. All logging statments for levels higher than ``CONFIG_LOG_DEFAULT_LEVEL`` will be removed by the preprocessor.
+
+At run time, all logs below ``CONFIG_LOG_DEFAULT_LEVEL`` are enabled by default. ``esp_log_set_level`` function may be used to set logging level per module. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.
+
+How to use this library
+-----------------------
+
+In each C file which uses logging functionality, define TAG variable like this:
+
+.. code-block:: c
+
+   static const char* TAG = "MyModule";
+
+then use one of logging macros to produce output, e.g:
+
+.. code-block:: c
+
+   ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);
+
+Several macros are available for different verbosity levels:
+
+* ``ESP_LOGE`` - error
+* ``ESP_LOGW`` - warning
+* ``ESP_LOGI`` - info
+* ``ESP_LOGD`` - debug
+* ``ESP_LOGV`` - verbose
+
+Additionally there is an _EARLY_ variant for each of these macros (e.g. ``ESP_EARLY_LOGE`` ).These variants can run in startup code, before heap allocator and syscalls have been initialized. When compiling bootloader, normal ``ESP_LOGx`` macros fall back to the same implementation as ``ESP_EARLY_LOGx`` macros. So the only place where ``ESP_EARLY_LOGx`` have to be used explicitly is the early startup code, such as heap allocator initialization code.
+
+(Note that such distinction would not have been necessary if we would have an ``ets_vprintf`` function in the ROM. Then it would be possible to switch implementation from _EARLY_ version to normal version on the fly. Unfortunately, ``ets_vprintf`` in ROM has been inlined by the compiler into ``ets_printf``, so it is not accessible outside.)
+
+To override default verbosity level at file or component scope, define ``LOG_LOCAL_LEVEL`` macro. At file scope, define it before including ``esp_log.h``, e.g.:
+
+.. code-block:: c
+
+   #define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
+   #include "esp_log.h"
+
+
+At component scope, define it in component makefile:
+
+.. code-block:: make
+
+   CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG
+
+To configure logging output per module at runtime, add calls to ``esp_log_set_level`` function:
+
+.. code-block:: c
+
+   esp_log_set_level("*", ESP_LOG_ERROR);        // set all components to ERROR level
+   esp_log_set_level("wifi", ESP_LOG_WARN);      // enable WARN logs from WiFi stack
+   esp_log_set_level("dhcpc", ESP_LOG_INFO);     // enable INFO logs from DHCP client
+

diff --git a/components/log/include/esp_log.h b/components/log/include/esp_log.h
index 8ca6e241d4c161ae3ebaf6d059a4e5cf15a63ace..2878dc50157bcb050fea6c27812ceb58c0776a80 100644 (file)
--- a/components/log/include/esp_log.h
+++ b/components/log/include/esp_log.h
@@ -24,76 +24,16 @@ extern "C" {
 #endif
 
 /**
- * @brief Logging library
- *
- * Log library has two ways of managing log verbosity: compile time, set via
- * menuconfig, and runtime, using esp_log_set_level function.
- *
- * At compile time, filtering is done using CONFIG_LOG_DEFAULT_LEVEL macro, set via
- * menuconfig. All logging statments for levels higher than CONFIG_LOG_DEFAULT_LEVEL
- * will be removed by the preprocessor.
- *
- * At run time, all logs below CONFIG_LOG_DEFAULT_LEVEL are enabled by default.
- * esp_log_set_level function may be used to set logging level per module.
- * Modules are identified by their tags, which are human-readable ASCII
- * zero-terminated strings.
- *
- * How to use this library:
- *
- * In each C file which uses logging functionality, define TAG variable like this:
- *
- *      static const char* TAG = "MyModule";
- *
- * then use one of logging macros to produce output, e.g:
- *
- *      ESP_LOGW(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);
- *
- * Several macros are available for different verbosity levels:
- *
- *      ESP_LOGE — error
- *      ESP_LOGW — warning
- *      ESP_LOGI — info
- *      ESP_LOGD - debug
- *      ESP_LOGV - verbose
- *
- * Additionally there is an _EARLY_ variant for each of these macros (e.g. ESP_EARLY_LOGE).
- * These variants can run in startup code, before heap allocator and syscalls
- * have been initialized.
- * When compiling bootloader, normal ESP_LOGx macros fall back to the same implementation
- * as ESP_EARLY_LOGx macros. So the only place where ESP_EARLY_LOGx have to be used explicitly
- * is the early startup code, such as heap allocator initialization code.
- *
- * (Note that such distinction would not have been necessary if we would have an
- * ets_vprintf function in the ROM. Then it would be possible to switch implementation
- * from _EARLY version to normal version on the fly. Unfortunately, ets_vprintf in ROM
- * has been inlined by the compiler into ets_printf, so it is not accessible outside.)
- *
- * To override default verbosity level at file or component scope, define LOG_LOCAL_LEVEL macro.
- * At file scope, define it before including esp_log.h, e.g.:
- *
- *      #define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
- *      #include "esp_log.h"
- *
- * At component scope, define it in component makefile:
- *
- *      CFLAGS += -D LOG_LOCAL_LEVEL=ESP_LOG_DEBUG
- *
- * To configure logging output per module at runtime, add calls to esp_log_set_level function:
- *
- *      esp_log_set_level("*", ESP_LOG_ERROR);        // set all components to ERROR level
- *      esp_log_set_level("wifi", ESP_LOG_WARN);      // enable WARN logs from WiFi stack
- *      esp_log_set_level("dhcpc", ESP_LOG_INFO);     // enable INFO logs from DHCP client
+ * @brief Log level
  *
  */
-
-
 typedef enum {
-    ESP_LOG_NONE,       // No log output
-    ESP_LOG_ERROR,      // Critical errors, software module can not recover on its own
-    ESP_LOG_WARN,       // Error conditions from which recovery measures have been taken
-    ESP_LOG_INFO,       // Information messages which describe normal flow of events
-    ESP_LOG_DEBUG,      // Extra information which is not necessary for normal use (values, pointers, sizes, etc).
-    ESP_LOG_VERBOSE     // Bigger chunks of debugging information, or frequent messages which can potentially flood the output.
+    ESP_LOG_NONE,       /*!< No log output */
+    ESP_LOG_ERROR,      /*!<  Critical errors, software module can not recover on its own */
+    ESP_LOG_WARN,       /*!< Error conditions from which recovery measures have been taken */
+    ESP_LOG_INFO,       /*!< Information messages which describe normal flow of events */
+    ESP_LOG_DEBUG,      /*!< Extra information which is not necessary for normal use (values, pointers, sizes, etc). */
+    ESP_LOG_VERBOSE     /*!< Bigger chunks of debugging information, or frequent messages which can potentially flood the output. */
 } esp_log_level_t;
 
 typedef int (*vprintf_like_t)(const char *, va_list);
@@ -143,7 +83,7 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
  *
  * @return timestamp, in milliseconds
  */
-uint32_t esp_log_timestamp();
+uint32_t esp_log_timestamp(void);
 
 
 #if CONFIG_LOG_COLORS