update docs

Author: tlambert03

src/scyjava/_stubs/_cli.py

@@ -1,4 +1,12 @@
-"""The scyjava-stubs executable."""
+"""The scyjava-stubs executable.
+
+Provides cli access to the `scyjava._stubs.generate_stubs` function.
+
+The only interesting additional things going on here is the choice of *where* the stubs
+go by default.  When using the CLI, they land in `scyjava.types` by default; see the
+`_get_ouput_dir` helper function for details on how the output directory is resolved
+from the CLI arguments.
+"""
 
 from __future__ import annotations
 

src/scyjava/_stubs/_dynamic_import.py

@@ -1,3 +1,24 @@
+"""Logic for using generated type stubs as runtime importable, with lazy JVM startup.
+
+Most often, the functionality here will be used as follows:
+
+```
+from scyjava._stubs import setup_java_imports
+
+__all__, __getattr__ = setup_java_imports(
+    __name__,
+    __file__,
+    endpoints=["org.scijava:parsington:3.1.0"],
+    base_prefix="org"
+)
+```
+
+...and that little snippet is written into the generated stubs modules by the
+`scyjava._stubs.generate_stubs` function.
+
+See docstring of `setup_java_imports` for details on how it works.
+"""
+
 import ast
 from logging import warning
 from pathlib import Path
@@ -21,11 +42,14 @@ def setup_java_imports(
     :param module_file: The path to the module file (usually `__file__` in the calling
         module).
     :param endpoints: A list of Java endpoints to add to the scyjava configuration.
+        (Note that `scyjava._stubs.generate_stubs` will automatically add the necessary
+        endpoints for the generated stubs.)
     :param base_prefix: The base prefix for the Java package name. This is used when
         determining the Java class path for the requested class. The java class path
         will be truncated to only the part including the base_prefix and after.  This
         makes it possible to embed a module in a subpackage (like `scyjava.types`) and
         still have the correct Java class path.
+
     :return: A 2-tuple containing:
         - A list of all classes in the module (as defined in the stub file), to be
             assigned to `__all__`.
@@ -57,6 +81,7 @@ def setup_java_imports(
         if ep not in scyjava.config.endpoints:
             scyjava.config.endpoints.append(ep)
 
+    # list intended to be assigned to `__all__` in the generated module.
     module_all = []
     try:
         my_stub = Path(module_file).with_suffix(".pyi")
@@ -75,6 +100,7 @@ def setup_java_imports(
         )
 
     def module_getattr(name: str, mod_name: str = module_name) -> Any:
+        """Function intended to be assigned to __getattr__ in the generate module."""
         if module_all and name not in module_all:
             raise AttributeError(f"module {module_name!r} has no attribute {name!r}")
 
@@ -84,6 +110,9 @@ def module_getattr(name: str, mod_name: str = module_name) -> Any:
 
         class_path = f"{mod_name}.{name}"
 
+        # Generate a proxy type (with a nice repr) that
+        # delays the call to `jimport` until the last moment when type.__new__ is called
+
         class ProxyMeta(type):
             def __repr__(self) -> str:
                 return f"<scyjava class {class_path!r}>"

src/scyjava/_stubs/_genstubs.py

@@ -1,3 +1,14 @@
+"""Type stub generation utilities using stubgen.
+
+This module provides utilities for generating type stubs for Java classes
+using the stubgenj library.  `stubgenj` must be installed for this to work
+(it, in turn, only depends on JPype).
+
+See `generate_stubs` for most functionality.  For the command-line tool,
+see `scyjava._stubs.cli`, which provides a CLI interface for the `generate_stubs`
+function.
+"""
+
 from __future__ import annotations
 
 import ast
@@ -42,9 +53,11 @@ def generate_stubs(
         The prefixes to generate stubs for. This should be a list of Java class
         prefixes that you expect to find in the endpoints. For example,
         ["org.apache.commons"].  If not provided, the prefixes will be
-        automatically determined from the jar files provided by endpoints.
+        automatically determined from the jar files provided by endpoints (see the
+        `_list_top_level_packages` helper function).
     output_dir : str | Path, optional
-        The directory to write the generated stubs to. Defaults to "stubs".
+        The directory to write the generated stubs to. Defaults to "stubs" in the
+        current working directory.
     convert_strings : bool, optional
         Whether to cast Java strings to Python strings in the stubs. Defaults to True.
         NOTE: This leads to type stubs that may not be strictly accurate at runtime.
@@ -58,8 +71,10 @@ def generate_stubs(
         Whether to include Javadoc in the generated stubs. Defaults to True.
     add_runtime_imports : bool, optional
         Whether to add runtime imports to the generated stubs. Defaults to True.
-        This is useful if you want to use the stubs as a runtime package with type
-        safety.
+        This is useful if you want to actually import the stubs as a runtime package
+        with type safety.  The runtime import "magic" depends on the
+        `scyjava._stubs.setup_java_imports` function.  See its documentation for
+        more details.
     remove_namespace_only_stubs : bool, optional
         Whether to remove stubs that export no names beyond a single
         `__module_protocol__`. This leaves some folders as PEP420 implicit namespace
@@ -95,7 +110,7 @@ def _patched_start(*args: Any, **kwargs: Any) -> None:
         ep_artifacts = tuple(ep.split(":")[1] for ep in endpoints)
         for j in cp.split(os.pathsep):
             if Path(j).name.startswith(ep_artifacts):
-                _prefixes.update(list_top_level_packages(j))
+                _prefixes.update(_list_top_level_packages(j))
 
     prefixes = sorted(_prefixes)
     logger.info(f"Using endpoints: {scyjava.config.endpoints!r}")
@@ -189,7 +204,7 @@ def ruff_check(output: Path, select: str = "E,W,F,I,UP,C4,B,RUF,TC,TID") -> None
     subprocess.run(["ruff", "format", *py_files, "--quiet"])
 
 
-def list_top_level_packages(jar_path: str) -> set[str]:
+def _list_top_level_packages(jar_path: str) -> set[str]:
     """Inspect a JAR file and return the set of top-level Java package names."""
     packages: set[str] = set()
     with ZipFile(jar_path, "r") as jar: