From ef39067ceb9ad9511fd107a9ee5810bf66e75a9e Mon Sep 17 00:00:00 2001
From: Max Kipp <jkipp@dewberry.com>
Date: Fri, 12 Sep 2025 13:16:23 -0400
Subject: [PATCH] Add notes on message levels to docstrings and Readme

---
 Readme.md            | 15 +++++++++++++++
 src/hecdss/hecdss.py |  8 ++++++--
 src/hecdss/native.py |  2 ++
 3 files changed, 23 insertions(+), 2 deletions(-)

diff --git a/Readme.md b/Readme.md
index ffdd443..d781322 100644
--- a/Readme.md
+++ b/Readme.md
@@ -121,6 +121,21 @@ This library uses (`hecdss.dll` on Windows and `libhecdss.so` on Unix/Linux).  h
    ```
 
 
+## Message Levels
+
+Message levels can be set using `set_global_debug_level` or `set_debug_level`, for example:
+
+```python
+from hecdss import HecDss
+mlvl: int = 4
+HecDss.set_global_debug_level(mlvl)
+```
+
+Common levels are described in the documentation for the `mlvl` parameter of the `zset` utility function from the [HEC-DSS Programmers Guide for C](https://www.hec.usace.army.mil/confluence/dssdocs/dsscprogrammer)
+
+Additional levels are described in the heclib source code C headers in [zdssMessages.h](https://github.com/HydrologicEngineeringCenter/hec-dss/blob/master/heclib/heclib_c/src/headers/zdssMessages.h)
+
+
 ## how to generate documentation
 
 pdoc -o docs -d google --no-show-source .\src
diff --git a/src/hecdss/hecdss.py b/src/hecdss/hecdss.py
index 164ab60..4781058 100644
--- a/src/hecdss/hecdss.py
+++ b/src/hecdss/hecdss.py
@@ -61,7 +61,9 @@ def set_global_debug_level(level: int) -> None:
         Sets the library debug level
 
         Args:
-            level (int): a value between 0 and 15. Larger for more output
+            level (int): a value between 0 and 15. Larger for more output.
+                For level descriptions, see zdssMessages.h of the heclib source code,
+                or documentation from the HEC-DSS Programmers Guide for C on the `mlvl` parameter of the `zset` utility function.
         """
         _Native().hec_dss_set_debug_level(level)
     def close(self):
@@ -743,7 +745,9 @@ def set_debug_level(self, level) -> int:
         """sets the DSS debug level.
 
         Args:
-            level (int): a value between 0 and 15. Larger for more output
+            level (int): a value between 0 and 15. Larger for more output.
+                For level descriptions, see zdssMessages.h of the heclib source code,
+                or documentation from the HEC-DSS Programmers Guide for C on the `mlvl` parameter of the `zset` utility function.
 
         Returns:
             int: _description_
diff --git a/src/hecdss/native.py b/src/hecdss/native.py
index d2f234d..8968de1 100644
--- a/src/hecdss/native.py
+++ b/src/hecdss/native.py
@@ -90,6 +90,8 @@ def __hec_dss_set_value(self, name: str, value: int):
     # set debug level (0-15)
     # 0 - no output
     # 15 - max output
+    # for additional levels: see zdssMessages.h of the heclib source code,
+    # or documentation from the HEC-DSS Programmers Guide for C on `mlvl` parameter of the `zset` utility function.
     def hec_dss_set_debug_level(self, value: int):
         self.__hec_dss_set_value("mlvl", value)