mpy-cross/mpy_cross: Add docstrings to public methods.

mpy-cross/mpy_cross/__init__.py

@@ -64,6 +64,13 @@ def _find_mpy_cross_binary(mpy_cross):
 
 
 def mpy_version(mpy_cross=None):
+    """
+    Get the version and sub-version of the .mpy file format generated by this version of mpy-cross.
+
+    Returns: A tuple of `(mpy_version, mpy_sub_version)`
+    Optional keyword arguments:
+     - mpy_cross: Specific mpy-cross binary to use
+    """
     version_info = run(["--version"], mpy_cross=mpy_cross)
     match = re.search(_VERSION_RE, version_info)
     mpy_version, mpy_sub_version = int(match.group(1)), int(match.group(2) or "0")
@@ -74,6 +81,22 @@ def mpy_version(mpy_cross=None):
 
 
 def compile(src, dest=None, src_path=None, opt=None, march=None, mpy_cross=None, extra_args=None):
+    """
+    Compile the specified .py file with mpy-cross.
+
+    Returns: Standard output from mpy-cross as a string.
+
+    Required arguments:
+     - src:        The path to the .py file
+
+    Optional keyword arguments:
+     - dest:       The output .mpy file. Defaults to `src` (with .mpy extension)
+     - src_path:   The path to embed in the .mpy file (defaults to `src`)
+     - opt:        Optimisation level (0-3, default 0)
+     - march:      One of the `NATIVE_ARCH_*` constants (defaults to NATIVE_ARCH_NONE)
+     - mpy_cross:  Specific mpy-cross binary to use
+     - extra_args: Additional arguments to pass to mpy-cross (e.g. `["-X", "emit=native"]`)
+    """
     if not src:
         raise ValueError("src is required")
     if not os.path.exists(src):
@@ -102,6 +125,15 @@ def compile(src, dest=None, src_path=None, opt=None, march=None, mpy_cross=None,
 
 
 def run(args, mpy_cross=None):
+    """
+    Run mpy-cross with the specified command line arguments.
+    Prefer to use `compile()` instead.
+
+    Returns: Standard output from mpy-cross as a string.
+
+    Optional keyword arguments:
+     - mpy_cross: Specific mpy-cross binary to use
+    """
     mpy_cross = _find_mpy_cross_binary(mpy_cross)
 
     if not os.path.exists(mpy_cross):