From 396a15f005e843456c67a8f3d0db41cd12a225de Mon Sep 17 00:00:00 2001
From: Paulo Meira <10246101+PMeira@users.noreply.github.com>
Date: Fri, 9 Feb 2024 03:57:54 -0300
Subject: [PATCH] Docs: Try to make it clearer that the `dss_lib` object is not
 intended for general usage.

---
 docs/notebooks/Example-OpenDSSDirect.py.ipynb | 18 ++++++++++++++----
 opendssdirect/OpenDSSDirect.py                | 11 +++++++++++
 2 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/docs/notebooks/Example-OpenDSSDirect.py.ipynb b/docs/notebooks/Example-OpenDSSDirect.py.ipynb
index 991396c..aebbb13 100644
--- a/docs/notebooks/Example-OpenDSSDirect.py.ipynb
+++ b/docs/notebooks/Example-OpenDSSDirect.py.ipynb
@@ -147,7 +147,19 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Sometimes it might be useful to use the low-level interface. Beware that error checking needs to done by the user in this case."
+    "## Low-level API (advanced topic)\n",
+    "\n",
+    "**If you are a new OpenDSS user, you are not expected to use the low-level interface, i.e. the `dss_lib` object is for advanced users only, and may change without warning.** \n",
+    "\n",
+    "The low-level interface exposes [DSS C-API](https://dss-extensions.org/dss_capi/dss__capi_8h.html) as wrapped in [DSS-Python](https://dss-extensions.org/dss_python/). It's useful to prototype low-level operations in Python before porting to C, which is not something most of the OpenDSS users will ever do.\n",
+    "\n",
+    "Still, in some rare occasions, it might be useful to use the low-level interface. Beware that error checking needs to done by the user in this case. \n",
+    "The reference for the low-level API is the source code of the DSS engine itself and the C header, e.g. \n",
+    "\n",
+    "- https://github.com/dss-extensions/dss_capi/blob/master/include/dss_capi.h\n",
+    "- https://dss-extensions.org/dss_capi/dss__capi_8h.html\n",
+    "\n",
+    "Advanced knowledge of DSS C-API, pointers, and the CFFI module are required."
    ]
   },
   {
@@ -164,9 +176,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Each of the properties from the official COM implementation of OpenDSS are implemented as a pair of functions. While in OpenDSSDirect.py one can use, e.g., `dss.Loads.kW()` to read the active load element `kW` and `dss.Loads.kW(some_value)` to set the `kW` value, the low-level interface exposes `dss.dss_lib.Loads_Get_kW()` and `dss.dss_lib.Loads_Set_kW()`.\n",
-    "\n",
-    "The low-level interface exposes [DSS C-API](https://dss-extensions.org/dss_capi/dss__capi_8h.html) as wrapped in DSS-Python. It's useful to prototype low-level operations in Python before porting to C."
+    "Each of the properties from the official COM implementation of OpenDSS is implemented as a pair of functions. While in OpenDSSDirect.py one can use, e.g., `dss.Loads.kW()` to read the active load element `kW` and `dss.Loads.kW(some_value)` to set the `kW` value, the low-level interface exposes `dss.dss_lib.Loads_Get_kW()` and `dss.dss_lib.Loads_Set_kW()`."
    ]
   },
   {
diff --git a/opendssdirect/OpenDSSDirect.py b/opendssdirect/OpenDSSDirect.py
index 0450fba..059ef6f 100644
--- a/opendssdirect/OpenDSSDirect.py
+++ b/opendssdirect/OpenDSSDirect.py
@@ -196,7 +196,18 @@ def __init__(self, ctx_api_util=None, prefer_lists=None):
         Base.__init__(self, ctx_api_util, prefer_lists=prefer_lists)
         OpenDSSDirect._ctx_to_dss[ctx_api_util.ctx] = self
         object.__setattr__(self, '_frozen_attrs', False)
+        
         self.dss_lib = ctx_api_util.lib
+        """
+        `dss_lib` provides access to the low-level CFFI library; this is not recommended for most users and may 
+        change across versions. The intention is to allow some (very) advanced operations directly, when the
+        high-level interface either does not model some specific detail, or when users know how to manually
+        address some data directly with lower overhead.
+
+        **WARNING**: if used incorrectly, could even crash your computer.
+        """
+
+
         self.dss_ffi = ctx_api_util.ffi
         self.dss = self