From 105dcead4890bee529f4ae9833892cdd1a4f8014 Mon Sep 17 00:00:00 2001
From: Robin Krahl <robin.krahl@ireas.org>
Date: Tue, 22 May 2018 12:02:06 +0200
Subject: Improve log level documentation

Now, the documentation clearly states the purpose of each log level.
Also, the documentation for set_log_level is corrected:  libnitrokey
always prints to stderr.
---
 TODO.md     |  1 -
 src/lib.rs  |  3 ++-
 src/util.rs | 19 ++++++++++---------
 3 files changed, 12 insertions(+), 11 deletions(-)

diff --git a/TODO.md b/TODO.md
index b06de85..8538715 100644
--- a/TODO.md
+++ b/TODO.md
@@ -36,7 +36,6 @@
   - `NK_list_devices_by_cpuID`
   - `NK_connect_with_ID`
 - Fix timing issues with the `totp` and `totp_pin` test cases.
-- Improve log level documentation.
 - Clear passwords from memory.
 - Find a nicer syntax for the `write_config` test.
 - Fix segmentation faults when freeing string literals with old Nitrokey
diff --git a/src/lib.rs b/src/lib.rs
index 46549c6..1cfb7fd 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -167,7 +167,8 @@ pub fn set_debug(state: bool) {
 }
 
 /// Sets the log level for libnitrokey.  All log messages are written to the
-/// standard output or standard errror.
+/// standard error stream.  Setting the log level enables all log messages on
+/// the same or on a higher log level.
 pub fn set_log_level(level: LogLevel) {
     unsafe {
         nitrokey_sys::NK_set_debug_level(level.into());
diff --git a/src/util.rs b/src/util.rs
index 8a6c411..d380de4 100644
--- a/src/util.rs
+++ b/src/util.rs
@@ -48,22 +48,23 @@ pub enum CommandStatus {
     Error(CommandError),
 }
 
-/// Log level for libnitrokey.
+/// Log level for libnitrokey.  Setting the log level to a lower level enables
+/// all output from higher levels too.  Currently, only the log levels `Warning`,
+/// `DebugL1`, `Debug` and `DebugL2` are actually used.
 #[derive(Debug, PartialEq)]
 pub enum LogLevel {
-    /// Only log error messages.
+    /// Error messages.  Currently not used.
     Error,
-    /// Log error messages and warnings.
+    /// Warning messages.
     Warning,
-    /// Log error messages, warnings and info messages.
+    /// Informational messages.  Currently not used.
     Info,
-    /// Log error messages, warnings, info messages and debug messages.
+    /// Basic debug messages, especially basic information on the sent and received packets.
     DebugL1,
-    /// Log error messages, warnings, info messages and detailed debug
-    /// messages.
+    /// Detailed debug messages, especially detailed information on the sent and received packets.
     Debug,
-    /// Log error messages, warnings, info messages and very detailed debug
-    /// messages.
+    /// Very detailed debug messages, especially detailed information about the control flow for
+    /// device communication (for example function entries and exits).
     DebugL2,
 }
 
-- 
cgit v1.2.1