From 7bdb00a58448155225e0f15cdf8523dae578c307 Mon Sep 17 00:00:00 2001
From: Sebastien Jourdain <sebastien.jourdain@kitware.com>
Date: Tue, 13 Aug 2024 09:52:55 -0600
Subject: [PATCH] fix(api): add doc to method definition

---
 trame_client/ui/core.py          |  3 +++
 trame_client/utils/web_module.py | 12 ++++++++++++
 2 files changed, 15 insertions(+)

diff --git a/trame_client/ui/core.py b/trame_client/ui/core.py
index d794964..0e6830e 100644
--- a/trame_client/ui/core.py
+++ b/trame_client/ui/core.py
@@ -219,6 +219,8 @@ def state(self):
 
     @property
     def ready(self):
+        """Start the server as a background task (if not already started)
+        and return the future that represent the status of that task."""
         if not self.server.running:
             # NoOp if already start[ing/ed]
             self.server.start(
@@ -268,6 +270,7 @@ def _jupyter_content(self):
 
     @property
     def ipywidget(self):
+        """Convert the UI into a ipywidget so it can be embedded in an ipywidget layout."""
         from ipywidgets.widgets import HTML
 
         return HTML(value=self._jupyter_content())
diff --git a/trame_client/utils/web_module.py b/trame_client/utils/web_module.py
index 3f78bbc..5943749 100644
--- a/trame_client/utils/web_module.py
+++ b/trame_client/utils/web_module.py
@@ -3,6 +3,7 @@
 
 
 def file_digest(file_path):
+    """Return the hex digest of a file"""
     h = hashlib.sha256()
     b = bytearray(128 * 1024)
     mv = memoryview(b)
@@ -13,6 +14,7 @@ def file_digest(file_path):
 
 
 def file_with_digest(file_path, digest=None, digest_size=40):
+    """Write a new file sibbling to file_path with a digest hash in his name"""
     file_path = Path(file_path)
 
     if digest is None:
@@ -29,6 +31,7 @@ def file_with_digest(file_path, digest=None, digest_size=40):
 
 
 def is_relative_to(path, *other_paths):
+    """Helper to check that *other_paths are nested under path"""
     # Convert the input path and the base path into absolute paths
     abs_path = path.resolve()
     abs_other_paths = [Path(other).resolve() for other in other_paths]
@@ -40,6 +43,10 @@ def is_relative_to(path, *other_paths):
 
 
 class WebModule:
+    """Helper class to create/define a module while dynamically computing hash
+    to properly prevent invalid browser cache.
+    """
+
     def __init__(self, vue_use=None, digest_size=6):
         self._digest_size = digest_size
         self._serving_entries = []
@@ -70,6 +77,7 @@ def _add_file(self, file_path):
         raise ValueError(f"No parent found for {file_path}")
 
     def serve_directory(self, directory_to_serve, www_base_name):
+        """Register a new directory to serve with its alias endpoint"""
         fs_path = Path(directory_to_serve).resolve()
         if not fs_path.exists():
             raise ValueError(
@@ -84,16 +92,20 @@ def serve_directory(self, directory_to_serve, www_base_name):
         self._serve[www_base_name] = str(fs_path)
 
     def add_script_file(self, file_path):
+        """Add a script file to serve while computing unique name and proper http path internally."""
         self._scripts.append(self._add_file(file_path))
 
     def add_style_file(self, file_path):
+        """Add a css file to serve while computing unique name and proper http path internally."""
         self._styles.append(self._add_file(file_path))
 
     def add_vue_use(self, vue_use):
+        """Register a vue plugin expression"""
         self._vue_use.append(vue_use)
 
     @property
     def module(self):
+        """Return the generated trame module as a dictionary."""
         return dict(
             serve=self._serve,
             scripts=self._scripts,