From de03b743fb33b468567c9e3c66bd09dc2dc32054 Mon Sep 17 00:00:00 2001
From: David Vierra <codewarrior@hawaii.rr.com>
Date: Sat, 17 Oct 2015 09:43:53 -1000
Subject: [PATCH] Add docstrings to createSchematic, extractSchematicFrom and
 Ray

---
 src/mceditlib/export.py    | 16 ++++++++++++++++
 src/mceditlib/geometry.py  | 24 ++++++++++++++++++++++++
 src/mceditlib/schematic.py | 31 ++++++++++++++++++++++++-------
 3 files changed, 64 insertions(+), 7 deletions(-)

diff --git a/src/mceditlib/export.py b/src/mceditlib/export.py
index a94ddc5..e4996a4 100644
--- a/src/mceditlib/export.py
+++ b/src/mceditlib/export.py
@@ -17,6 +17,22 @@ log = logging.getLogger(__name__)
 
 
 def extractSchematicFrom(sourceDim, box, *a, **kw):
+    """
+    Extract a schematic from the given dimension within the given selection box. The
+    minimum corner of the given box becomes the schematic's (0,0,0) coordinate.
+
+    Parameters
+    ----------
+    sourceDim : WorldEditorDimension
+    box : SelectionBox
+    a :
+    kw :
+
+    Returns
+    -------
+    WorldEditor
+
+    """
     return exhaust(extractSchematicFromIter(sourceDim, box, *a, **kw))
 
 
diff --git a/src/mceditlib/geometry.py b/src/mceditlib/geometry.py
index 5195b17..3e3c610 100644
--- a/src/mceditlib/geometry.py
+++ b/src/mceditlib/geometry.py
@@ -141,6 +141,30 @@ class Vector(namedtuple("_Vector", ("x", "y", "z"))):
 
 
 class Ray(object):
+    """
+    A ray in 3D space, starting at an origin point and extending in a direction given
+    by a vector
+
+    Parameters
+    ----------
+    point: Vector
+        The ray's origin point
+    vector: Vector
+        The ray's direction vector
+
+    Attributes
+    ----------
+
+    point: Vector
+    vector: Vector
+
+    Methods
+    ----------
+
+    atHeight(h: int) : Vector
+        Return the intersection of this vector with the plane at y=h.  If the ray
+        does not intersect the plane, returns the ray's origin.
+    """
 
     def __init__(self, point, vector):
         self.point = Vector(*point)
diff --git a/src/mceditlib/schematic.py b/src/mceditlib/schematic.py
index 9d5ecb1..c0ea2f4 100644
--- a/src/mceditlib/schematic.py
+++ b/src/mceditlib/schematic.py
@@ -28,6 +28,18 @@ log = getLogger(__name__)
 blocktypeClassesByName = {"Alpha": PCBlockTypeSet}
 
 def createSchematic(shape, blocktypes='Alpha'):
+    """
+    Create a new .schematic of the given shape and blocktypes and return a WorldEditor.
+
+    Parameters
+    ----------
+    shape : tuple of int
+    blocktypes : BlockTypeSet or str
+
+    Returns
+    -------
+    WorldEditor
+    """
     from mceditlib.worldeditor import WorldEditor
 
     adapter = SchematicFileAdapter(shape=shape, blocktypes=blocktypes)
@@ -69,15 +81,20 @@ class SchematicFileAdapter(FakeChunkedLevelAdapter):
         the file is y,z,x. This is the same order used in Minecraft 1.4's
         chunk sections.
 
-        :type shape: tuple
-        :param shape: The shape of the schematic as (x, y, z)
-        :type filename: basestring
-        :param filename: Path to a file to load a saved schematic from.
-        :type blocktypes: basestring or BlockTypeSet
-        :param blocktypes: The name of a builtin blocktypes set (one of
+        Parameters
+        ----------
+        shape: tuple of int
+            The shape of the schematic as (x, y, z)
+        filename: basestring
+            Path to a file to load a saved schematic from.
+        blocktypes: basestring or BlockTypeSet
+            The name of a builtin blocktypes set (one of
             "Classic", "Alpha", "Pocket") to indicate allowable blocks. The default
             is Alpha. An instance of BlockTypeSet may be passed instead.
-        :rtype: SchematicFileAdapter
+
+        Returns
+        ----------
+        SchematicFileAdapter
 
         """
         self.EntityRef = PCEntityRef