Repository: numba/numba

Issue:
Add inspect_types (etc) docstrings
## Feature request

When I use tab-completion to explore my jit-compiled functions, I see `inspect_*` methods that are actually super useful. However, if I want to see a description of what they do, I need to go online [here](http://numba.pydata.org/numba-doc/0.18.1/reference/compilation.html). Doing `inspect_asm?` in IPython yields `<no docstring>`. It would be great if the methods contained these docstrings, not to mention a link to more extensive documentation about how to read the resulting output.


Discussion:
Thanks for the request, this is a good point. Would you be interested in creating a patch to add these docstrings? It would be most welcome. Thanks!

Sounds like a good item for the SciPy sprints.  :)
@seibert it was! Sorry that I was too busy with other stuff! Would you be able to point me to the right place to look in the codebase?
@jni, https://github.com/numba/numba/blob/37ab1420fa87d02b635991b32f0faf5c65e8fc4d/numba/dispatcher.py#L397-L461, thanks.

Resolving patch:
diff --git a/numba/cuda/codegen.py b/numba/cuda/codegen.py
--- a/numba/cuda/codegen.py
+++ b/numba/cuda/codegen.py
@@ -36,7 +36,7 @@ def _finalize_specific(self):
                 gv.name = gv.name.replace('.', '_')
 
     def get_asm_str(self):
-        # Return nothing: we can only dump assembler code when it is later
+        # Return nothing: we can only dump assembly code when it is later
         # generated (in numba.cuda.compiler).
         return None
 
diff --git a/numba/dispatcher.py b/numba/dispatcher.py
--- a/numba/dispatcher.py
+++ b/numba/dispatcher.py
@@ -395,6 +395,21 @@ def error_rewrite(e, issue_type):
             raise e
 
     def inspect_llvm(self, signature=None):
+        """Get the LLVM intermediate representation generated by compilation.
+
+        Parameters
+        ----------
+        signature : tuple of numba types, optional
+            Specify a signature for which to obtain the LLVM IR. If None, the
+            IR is returned for all available signatures.
+
+        Returns
+        -------
+        llvm : dict[signature, str] or str
+            Either the LLVM IR string for the specified signature, or, if no
+            signature was given, a dictionary mapping signatures to LLVM IR
+            strings.
+        """
         if signature is not None:
             lib = self.overloads[signature].library
             return lib.get_llvm_str()
@@ -402,23 +417,57 @@ def inspect_llvm(self, signature=None):
         return dict((sig, self.inspect_llvm(sig)) for sig in self.signatures)
 
     def inspect_asm(self, signature=None):
+        """Get the generated assembly code.
+
+        Parameters
+        ----------
+        signature : tuple of numba types, optional
+            Specify a signature for which to obtain the assembly code. If
+            None, the assembly code is returned for all available signatures.
+
+        Returns
+        -------
+        asm : dict[signature, str] or str
+            Either the assembly code for the specified signature, or, if no
+            signature was given, a dictionary mapping signatures to assembly
+            code.
+        """
         if signature is not None:
             lib = self.overloads[signature].library
             return lib.get_asm_str()
 
         return dict((sig, self.inspect_asm(sig)) for sig in self.signatures)
 
-    def inspect_types(self, file=None, signature=None, **kwargs):
-        """
-        print or return annotated source with Numba intermediate IR
+    def inspect_types(self, file=None, signature=None,
+                      pretty=False, style='default', **kwargs):
+        """Print/return Numba intermediate representation (IR)-annotated code.
 
-        Pass `pretty=True` to attempt color highlighting, and HTML rendering in
-        Jupyter and IPython by returning an Annotate Object. `file` must be
-        None if used in conjunction with `pretty=True`.
+        Parameters
+        ----------
+        file : file-like object, optional
+            File to which to print. Defaults to sys.stdout if None. Must be
+            None if ``pretty=True``.
+        signature : tuple of numba types, optional
+            Print/return the intermediate representation for only the given
+            signature. If None, the IR is printed for all available signatures.
+        pretty : bool, optional
+            If True, an Annotate object will be returned that can render the
+            IR with color highlighting in Jupyter and IPython. ``file`` must
+            be None if ``pretty`` is True. Additionally, the ``pygments``
+            library must be installed for ``pretty=True``.
+        style : str, optional
+            Choose a style for rendering. Ignored if ``pretty`` is ``False``.
+            This is directly consumed by ``pygments`` formatters. To see a
+            list of available styles, import ``pygments`` and run
+            ``list(pygments.styles.get_all_styles())``.
+
+        Returns
+        -------
+        annotated : Annotate object, optional
+            Only returned if ``pretty=True``, otherwise this function is only
+            used for its printing side effect. If ``pretty=True``, an Annotate
+            object is returned that can render itself in Jupyter and IPython.
         """
-        pretty = kwargs.get('pretty', False)
-        style = kwargs.get('style', 'default')
-
         overloads = self.overloads
         if signature is not None:
             overloads = {signature: self.overloads[signature]}


Test patch: