finish docs

d20/diceast.py

@@ -68,6 +68,8 @@ def comma(self, _):
 
 # ===== helper mixin =====
 class ChildMixin:
+    """A mixin that tree nodes must implement to support tree traversal utilities."""
+
     @property
     def children(self):
         """
@@ -109,9 +111,10 @@ def _child_set_check(self, index):
 
     def set_child(self, index, value):
         """
-        Sets the ith child of this Number.
+        Sets the ith child of this object.
 
-        :type index: int
+        :param int index: The index of the value to set.
+        :param value: The new value to set it to.
         :type value: ChildMixin
         """
         self._child_set_check(index)
@@ -120,10 +123,19 @@ def set_child(self, index, value):
 
 # ===== ast classes =====
 class Node(abc.ABC, ChildMixin):
+    """
+    The base class for all AST nodes.
+
+    A Node has no specific attributes, but supports all the methods in :class:`~d20.ast.ChildMixin` for traversal.
+    """
+
     # overridden here for type checking
     def set_child(self, index, value):
         """
-        :type index: int
+        Sets the ith child of this Node.
+
+        :param int index: Which child to set.
+        :param value: The Node to set it to.
         :type value: Node
         """
         super().set_child(index, value)
@@ -138,6 +150,7 @@ def __str__(self):
 
 
 class Expression(Node):  # expr
+    """Expressions are usually the root of all ASTs."""
     __slots__ = ("roll", "comment")
 
     def __init__(self, roll, comment=None):
@@ -159,6 +172,7 @@ def __str__(self):
 
 
 class AnnotatedNumber(Node):  # numexpr
+    """Represents a value with an annotation."""
     __slots__ = ("value", "annotations")
 
     def __init__(self, value, *annotations):

d20/expression.py

@@ -14,6 +14,8 @@
 class Number(abc.ABC, ast.ChildMixin):  # num
     """
     The base class for all expression objects.
+
+    Note that Numbers implement all the methods of a :class:`~d20.ast.ChildMixin`.
     """
 
     __slots__ = ("kept", "annotation")

d20/utils.py

@@ -7,12 +7,18 @@ def ast_adv_copy(ast, advtype):
     """
     Returns a minimally shallow copy of a dice AST with respect to advantage.
 
+    >>> tree = parse("1d20 + 5")
+    >>> str(tree)
+    '1d20 + 5'
+    >>> str(ast_adv_copy(tree, AdvType.ADV))
+    '2d20kh1 + 5'
+
     :param ast: The parsed AST.
-    :type ast: d20.diceast.Node
+    :type ast: d20.ast.Node
     :param advtype: The advantage type to roll at.
     :type advtype: d20.AdvType
     :return: The copied AST.
-    :rtype: d20.diceast.Node
+    :rtype: d20.ast.Node
     """
     root = copy.copy(ast)
     if not advtype:
@@ -65,9 +71,10 @@ def simplify_expr_annotations(expr, ambig_inherit=None):
     "1d20 (4) + 3 [foo] = 7"
 
     :param expr: The expression to transform.
-    :type expr: d20.expression.Number
-    :param ambig_inherit: When encountering a child node with no annotation and the parent has ambiguous types, which to inherit. Can be None for no inherit, 'left' for leftmost, or 'right' for rightmost.
-    :type ambig_inherit: Optional[Literal['left', 'right']]
+    :type expr: d20.Number
+    :param ambig_inherit: When encountering a child node with no annotation and the parent has ambiguous types, which \
+    to inherit. Can be ``None`` for no inherit, ``'left'`` for leftmost, or ``'right'`` for rightmost.
+    :type ambig_inherit: str
     """
     if ambig_inherit not in ('left', 'right', None):
         raise ValueError("ambig_inherit must be 'left', 'right', or None.")
@@ -112,7 +119,7 @@ def simplify_expr(expr, **kwargs):
     "7 [foo] - 2 [bar] = 5"
 
     :param expr: The expression to transform.
-    :type expr: d20.expression.Expression
+    :type expr: d20.Expression
     :param kwargs: Arguments that are passed to :func:`simplify_expr_annotations`.
     """
     simplify_expr_annotations(expr.roll, **kwargs)
@@ -145,9 +152,11 @@ def do_simplify(node, first=False):
 
 def tree_map(func, node):
     """
-    Returns a copy of the tree, with each node replaced with func(node).
+    Returns a copy of the tree, with each node replaced with ``func(node)``.
 
+    :param func: A transformer function.
     :type func: typing.Callable[[d20.ast.ChildMixin], d20.ast.ChildMixin]
+    :param node: The root of the tree to transform.
     :type node: d20.ast.ChildMixin
     """
     copied = copy.copy(node)
@@ -160,6 +169,7 @@ def leftmost(root):
     """
     Returns the leftmost leaf in this tree.
 
+    :param root: The root node of the tree.
     :type root: d20.ast.ChildMixin
     :rtype: d20.ast.ChildMixin
     """
@@ -173,6 +183,7 @@ def rightmost(root):
     """
     Returns the rightmost leaf in this tree.
 
+    :param root: The root node of the tree.
     :type root: d20.ast.ChildMixin
     :rtype: d20.ast.ChildMixin
     """
@@ -184,9 +195,11 @@ def rightmost(root):
 
 def dfs(node, predicate):
     """
-    Returns the first node in the tree such that predicate(node) is True, searching depth-first left-to-right.
+    Returns the first node in the tree such that ``predicate(node)`` is True, searching depth-first left-to-right.
 
+    :param node: The root node of the tree.
     :type node: d20.ast.ChildMixin
+    :param predicate: A predicate function.
     :type predicate: typing.Callable[[d20.ast.ChildMixin], bool]
     :rtype: d20.ast.ChildMixin
     """

docs/ast.rst

@@ -1,5 +1,168 @@
 Abstract Syntax Tree
 ====================
 
-TODO
+This page documents the structure of the Expression object as returned by ``parse(...)``. If you're looking
+for the Expression object returned by ``roll(...)expr``, check out :ref:`Expression Tree`.
+
+.. autoclass:: d20.ast.ChildMixin
+
+    .. method:: children
+        :property:
+
+        (read-only) The children of this object, usually used for traversing a tree.
+
+        :rtype: list[Node]
+
+    .. method:: left
+        :property:
+
+        The leftmost child of this object, usually used for traversing a tree.
+
+        :rtype: Node
+
+    .. method:: right
+        :property:
+
+        The rightmost child of this object, usually used for traversing a tree..
+
+        :rtype: Node
+
+    .. automethod:: set_child
+
+.. autoclass:: d20.ast.Node
+    :show-inheritance:
+
+.. autoclass:: d20.ast.Expression
+    :show-inheritance:
+
+    .. attribute:: roll
+        :type: d20.ast.Node
+
+        The subtree representing the expression's roll.
+
+    .. attribute:: comment
+        :type: Optional[str]
+
+        The comment of this expression.
+
+.. autoclass:: d20.ast.AnnotatedNumber
+    :show-inheritance:
+
+    .. attribute:: value
+        :type: d20.ast.Node
+
+        The subtree representing the annotated value.
+
+    .. attribute:: annotations
+        :type: list[str]
+
+        The annotations on the value.
+
+.. autoclass:: d20.ast.Literal
+    :show-inheritance:
+
+    .. attribute:: value
+        :type: Union[int, float]
+
+        The literal number represented.
+
+.. autoclass:: d20.ast.Parenthetical
+    :show-inheritance:
+
+    .. attribute:: value
+        :type: d20.ast.Node
+
+        The subtree inside the parentheses.
+
+.. autoclass:: d20.ast.UnOp
+    :show-inheritance:
+
+    .. attribute:: op
+        :type: str
+
+        The unary operation.
+
+    .. attribute:: value
+        :type: d20.ast.Node
+
+        The subtree that the operation operates on.
+
+.. autoclass:: d20.ast.BinOp
+    :show-inheritance:
+
+    .. attribute:: op
+        :type: str
+
+        The binary operation.
+
+    .. attribute:: left
+        :type: d20.ast.Node
+
+        The left subtree that the operation operates on.
+
+    .. attribute:: right
+        :type: d20.ast.Node
+
+        The right subtree that the operation operates on.
+
+.. autoclass:: d20.ast.OperatedSet
+    :show-inheritance:
+
+    .. attribute:: value
+        :type: d20.ast.NumberSet
+
+        The set to be operated on.
+
+    .. attribute:: operations
+        :type: list[d20.SetOperation]
+
+        The operations to run on the set.
+
+.. autoclass:: d20.ast.NumberSet
+    :show-inheritance:
+
+    .. attribute:: values
+        :type: list[d20.ast.NumberSet]
+
+        The elements of the set.
+
+.. autoclass:: d20.ast.OperatedDice
+    :show-inheritance:
+
+.. autoclass:: d20.ast.Dice
+    :show-inheritance:
+
+    .. attribute:: num
+        :type: int
+
+        The number of dice to roll.
+
+    .. attribute:: size
+        :type: int
+
+        How many sides each die should have.
+
+.. autoclass:: d20.ast.SetOperator
+
+    .. attribute:: op
+        :type: str
+
+        The operation to run on the selected elements of the set.
+
+    .. attribute:: sels
+        :type: list[d20.SetSelector]
+
+        The selectors that describe how to select operands.
+
+.. autoclass:: d20.ast.SetSelector
+
+    .. attribute:: cat
+        :type: Optional[str]
+
+        The type of selection (lowest, highest, literal, etc).
+
+    .. attribute:: num
+        :type: int
+
+        The number to select (the N in lowest/highest/etc N, or literally N).
 

docs/expression.rst

@@ -7,6 +7,7 @@ for the Expression object returned by ``parse(...)``, check out :ref:`Abstract S
 
 .. autoclass:: d20.Number
     :members: number, total, set, keptset, drop
+    :show-inheritance:
 
     .. attribute:: kept
         :type: bool

docs/index.rst

@@ -14,6 +14,7 @@ Welcome to d20's documentation!
    api
    expression
    ast
+   utils
 
 
 

docs/utils.rst

@@ -0,0 +1,5 @@
+Utilities
+=========
+
+.. automodule:: d20.utils
+    :members: