log: clean up docs, clarify esp_log_level_set usage

Closes https://github.com/espressif/esp-idf/issues/1713

components/log/README.rst

@@ -4,11 +4,15 @@ Logging library
 Overview
 --------
 
-Log library has two ways of managing log verbosity: compile time, set via menuconfig; and runtime, using ``esp_log_level_set`` function.
+Log library has two ways of managing log verbosity: compile time, set via menuconfig; and runtime, using :cpp:func:`esp_log_level_set` function.
 
-At compile time, filtering is done using ``CONFIG_LOG_DEFAULT_LEVEL`` macro, set via menuconfig. All logging statements for levels higher than ``CONFIG_LOG_DEFAULT_LEVEL`` will be removed by the preprocessor.
+The log levels are Error, Warning, Info, Debug, and Verbose (from lowest to highest level of verbosity).
 
-At run time, all logs below ``CONFIG_LOG_DEFAULT_LEVEL`` are enabled by default. ``esp_log_level_set`` function may be used to set logging level per module. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.
+At compile time, filtering is done using :ref:`CONFIG_LOG_DEFAULT_LEVEL` option, set via menuconfig. All logging statements for levels higher than :ref:`CONFIG_LOG_DEFAULT_LEVEL` will be removed by the preprocessor.
+
+At run time, all logs below :ref:`CONFIG_LOG_DEFAULT_LEVEL` are enabled by default. :cpp:func:`esp_log_level_set` function may be used to reduce logging level per module. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings. 
+
+Note that :cpp:func:`esp_log_level_set` can not increase logging level beyound that set by :ref:`CONFIG_LOG_DEFAULT_LEVEL`. To increase log level for a specific file at compile time, `LOG_LOCAL_LEVEL` macro can be used (see below for details).
 
 How to use this library
 -----------------------
@@ -27,15 +31,13 @@ then use one of logging macros to produce output, e.g:
 
 Several macros are available for different verbosity levels:
 
-* ``ESP_LOGE`` - error
+* ``ESP_LOGE`` - error (lowest)
 * ``ESP_LOGW`` - warning
 * ``ESP_LOGI`` - info
 * ``ESP_LOGD`` - debug
-* ``ESP_LOGV`` - verbose
+* ``ESP_LOGV`` - verbose (highest)
 
-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.
+Additionally there is an ``_EARLY`` variant for each of these macros (e.g. :c:macro:`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.:
 
@@ -51,7 +53,7 @@ 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_level_set`` function:
+To configure logging output per module at runtime, add calls to :cpp:func:`esp_log_level_set` function:
 
 .. code-block:: c
 
@@ -62,5 +64,5 @@ To configure logging output per module at runtime, add calls to ``esp_log_level_
 Logging to Host via JTAG
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-By default logging library uses vprintf-like function to write formatted output to dedicated UART. With calling a simple API, all log output my be routed to JTAG instead, and make the logging several times faster. For details please refer to section :ref:`app_trace-logging-to-host`.
+By default logging library uses vprintf-like function to write formatted output to dedicated UART. By calling a simple API, all log output may be routed to JTAG instead, making logging several times faster. For details please refer to section :ref:`app_trace-logging-to-host`.
 

components/log/include/esp_log.h

@@ -44,10 +44,18 @@ typedef int (*vprintf_like_t)(const char *, va_list);
  *
  * If logging for given component has already been enabled, changes previous setting.
  *
+ * Note that this function can not raise log level above the level set using
+ * CONFIG_LOG_DEFAULT_LEVEL setting in menuconfig.
+ *
+ * To raise log level above the default one for a given file, define
+ * LOG_LOCAL_LEVEL to one of the ESP_LOG_* values, before including
+ * esp_log.h in this file.
+ *
  * @param tag Tag of the log entries to enable. Must be a non-NULL zero terminated string.
  *            Value "*" resets log level for all tags to the given value.
  *
- * @param level  Selects log level to enable. Only logs at this and lower levels will be shown.
+ * @param level  Selects log level to enable. Only logs at this and lower verbosity
+ * levels will be shown.
  */
 void esp_log_level_set(const char* tag, esp_log_level_t level);
 
@@ -98,6 +106,8 @@ uint32_t esp_log_early_timestamp(void);
  */
 void esp_log_write(esp_log_level_t level, const char* tag, const char* format, ...) __attribute__ ((format (printf, 3, 4)));
 
+/** @cond */
+
 #include "esp_log_internal.h"
 
 #ifndef LOG_LOCAL_LEVEL
@@ -108,15 +118,14 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
 #endif
 #endif
 
+/** @endcond */
+
 /**
  * @brief Log a buffer of hex bytes at specified level, separated into 16 bytes each line.
  *
  * @param  tag      description tag
- *
  * @param  buffer   Pointer to the buffer array
- *
  * @param  buff_len length of buffer in bytes
- *
  * @param  level    level of the log
  *
  */
@@ -131,11 +140,8 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
  * @brief Log a buffer of characters at specified level, separated into 16 bytes each line. Buffer should contain only printable characters.
  *
  * @param  tag      description tag
- *
  * @param  buffer   Pointer to the buffer array
- *
  * @param  buff_len length of buffer in bytes
- *
  * @param  level    level of the log
  *
  */
@@ -158,11 +164,8 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
  * It is highly recommend to use terminals with over 102 text width.
  * 
  * @param tag description tag
- * 
  * @param buffer Pointer to the buffer array
- * 
  * @param buff_len length of buffer in bytes
- * 
  * @param level level of the log
  */
 #define ESP_LOG_BUFFER_HEXDUMP( tag, buffer, buff_len, level ) \
@@ -176,9 +179,7 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
  * @brief Log a buffer of hex bytes at Info level
  *
  * @param  tag      description tag
- *
  * @param  buffer   Pointer to the buffer array
- *
  * @param  buff_len length of buffer in bytes
  *
  * @see ``esp_log_buffer_hex_level``
@@ -195,9 +196,7 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
  * @brief Log a buffer of characters at Info level. Buffer should contain only printable characters.
  *
  * @param  tag      description tag
- *
  * @param  buffer   Pointer to the buffer array
- *
  * @param  buff_len length of buffer in bytes
  *
  * @see ``esp_log_buffer_char_level``
@@ -210,6 +209,7 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
         }\
     } while(0)
 
+/** @cond */
 
 //to be back compatible
 #define esp_log_buffer_hex      ESP_LOG_BUFFER_HEX
@@ -243,6 +243,8 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
 
 #define LOG_FORMAT(letter, format)  LOG_COLOR_ ## letter #letter " (%d) %s: " format LOG_RESET_COLOR "\n"
 
+/** @endcond */
+
 /// macro to output logs in startup code, before heap allocator and syscalls have been initialized. log at ``ESP_LOG_ERROR`` level. @see ``printf``,``ESP_LOGE``
 #define ESP_EARLY_LOGE( tag, format, ... ) ESP_LOG_EARLY_IMPL(tag, format, ESP_LOG_ERROR,   E, ##__VA_ARGS__)
 /// macro to output logs in startup code at ``ESP_LOG_WARN`` level.  @see ``ESP_EARLY_LOGE``,``ESP_LOGE``, ``printf``
@@ -287,11 +289,8 @@ void esp_log_write(esp_log_level_t level, const char* tag, const char* format, .
 /** runtime macro to output logs at a specified level.
  * 
  * @param tag tag of the log, which can be used to change the log level by ``esp_log_level_set`` at runtime.
- *
  * @param level level of the output log.
- *
  * @param format format of the output log. see ``printf``
- *
  * @param ... variables to be replaced into the log. see ``printf``
  *
  * @see ``printf``