Document loopy flags

loopy/flags.py

@@ -29,22 +29,77 @@ import re
 
 class Flags(Record):
     """
+    Unless otherwise specified, these flags are Boolean-valued
+    (i.e. on/off).
+
     .. rubric:: Code-generation flags
 
     .. attribute:: annotate_inames
+
+        When generating code for inames, annotate them with
+        comments if it is not immediately apparent which
+        iname is being referred to (such as for inames mapped
+        to constants or OpenCL group/local IDs).
+
     .. attribute:: trace_assignments
+
+        Generate code that uses *printf* in kernels to trace the
+        execution of assignment instructions.
+
     .. attribute:: trace_assignment_values
 
+        Like :attr:`trace_assignments`, but also trace the
+        assigned values.
+
     .. rubric:: Invocation-related flags
 
     .. attribute:: skip_arg_checks
+
+        Do not do any checking (data type, data layout, shape,
+        etc.) on arguments for a minor performance gain.
+
     .. attribute:: no_numpy
+
+        Do not check for or accept :mod:`numpy` arrays as
+        arguments.
+
     .. attribute:: return_dict
+
+        Have kernels return a :class:`dict` instead of a tuple as
+        output. Specifically, the result of a kernel invocation
+        with this flag is a tuple ``(evt, out_dict)``, where
+        *out_dict* is a dictionary mapping argument names to their
+        output values. This is helpful if arguments are inferred
+        and argument ordering is thus implementation-defined.
+
+        See :meth:`CompiledKernel.__call__`.
+
     .. attribute:: write_wrapper
+
+        Print the generated Python invocation wrapper.
+        Accepts a file name as a value. Writes to
+        ``sys.stdout`` if none is given.
+
     .. attribute:: highlight_wrapper
+
+        Use syntax highlighting in :attr:`write_wrapper`.
+
     .. attribute:: write_cl
+
+        Print the generate OpenCL kernel.
+        Accepts a file name as a value. Writes to
+        ``sys.stdout`` if none is given.
+
     .. attribute:: highlight_cl
+
+        Use syntax highlighting in :attr:`write_cl`.
+
     .. attribute:: edit_cl
+
+        Invoke an editor (given by the environment variable
+        :envvar:`EDITOR`) on the generated kernel code,
+        allowing for tweaks before the code is passed on to
+        the OpenCL implementation for compilation.
     """
 
     def __init__(