From e06105e878ca04db9573d5f6e5612dd49dbc22e5 Mon Sep 17 00:00:00 2001
From: tymokvo <tymokvo@gmail.com>
Date: Mon, 4 Dec 2017 09:16:30 -0800
Subject: [PATCH] added some documentation/examples

---
 .../ifcopenshell/entity_instance.py           | 29 ++++++++++++++++
 src/ifcopenshell-python/ifcopenshell/file.py  | 34 +++++++++++++++++++
 .../ifcopenshell/geom/main.py                 | 23 +++++++++++--
 3 files changed, 84 insertions(+), 2 deletions(-)

diff --git a/src/ifcopenshell-python/ifcopenshell/entity_instance.py b/src/ifcopenshell-python/ifcopenshell/entity_instance.py
index c287d578e0..f2c88fa398 100644
--- a/src/ifcopenshell-python/ifcopenshell/entity_instance.py
+++ b/src/ifcopenshell-python/ifcopenshell/entity_instance.py
@@ -34,6 +34,22 @@ except ImportError as e:
 
 
 class entity_instance(object):
+    """
+    This is the base python class for all IFC objects.
+
+    An instantiated entity_instance will have methods of Python and the IFC class itself.
+
+    example:
+
+    ifc_file = ifcopenshell.open(file_path)
+    products = ifc_file.by_type("IfcProduct")
+
+    print(products[0].__class__)
+    >>> <class 'ifcopenshell.entity_instance.entity_instance'>
+
+    print(products[0].Representation)
+    >>> #423=IfcProductDefinitionShape($,$,(#409,#421))
+    """
     def __init__(self, e):
         if isinstance(e, str):
             e = ifcopenshell_wrapper.new_IfcBaseClass(e)
@@ -138,6 +154,19 @@ class entity_instance(object):
         )))
 
     def get_info(self, include_identifier=True, recursive=False, return_type=dict, ignore=()):
+        """
+        Return a dictionary of the entity_instance's properties (Python and IFC) and their values.
+
+        example:
+
+        ifc_file = ifcopenshell.open(file_path)
+        products = ifc_file.by_type("IfcProduct")
+        obj_info = products[0].get_info()
+        print(obj_info.keys())
+
+        >>> dict_keys(['Description', 'Name', 'BuildingAddress', 'LongName', 'GlobalId', 'ObjectPlacement', 'OwnerHistory', 'ObjectType',
+        >>> ...'ElevationOfTerrain', 'CompositionType', 'id', 'Representation', 'type', 'ElevationOfRefHeight'])
+        """
         def _():
             try:
                 if include_identifier:
diff --git a/src/ifcopenshell-python/ifcopenshell/file.py b/src/ifcopenshell-python/ifcopenshell/file.py
index dfe5b6b933..183ef690e0 100644
--- a/src/ifcopenshell-python/ifcopenshell/file.py
+++ b/src/ifcopenshell-python/ifcopenshell/file.py
@@ -36,6 +36,25 @@ except NameError:
 
 
 class file(object):
+    """
+    Base class for containing IFC files.
+
+    Class has instance methods for filtering by element Id, Type, etc.
+
+    Instantiated objects can be subscripted by Id or Guid
+
+    example:
+
+    ifc_file = ifcopenshell.open(file_path)
+    products = ifc_file.by_type("IfcProduct")
+
+    print(products[0].id(), products[0].GlobalId)
+    >>> 122 2XQ$n5SLP5MBLyL442paFx
+
+    # Subscripting
+    print(products[0] == ifc_file[122] == ifc_file['2XQ$n5SLP5MBLyL442paFx'])
+    >>> True
+    """
     def __init__(self, f=None):
         self.wrapped_data = f or ifcopenshell_wrapper.file()
 
@@ -62,9 +81,19 @@ class file(object):
             return entity_instance(self.wrapped_data.by_guid(str(key)))
 
     def by_id(self, id):
+        """
+        Return IFC objects filtered by IFC ID.
+
+        Returned objects are unwrapped IFC objects.
+        """
         return self[id]
 
     def by_guid(self, guid):
+        """
+        Return IFC objects filtered by IFC GUID.
+
+        Returned objects are unwrapped IFC objects.
+        """
         return self[guid]
 
     def add(self, inst):
@@ -72,6 +101,11 @@ class file(object):
         return entity_instance(self.wrapped_data.add(inst.wrapped_data))
 
     def by_type(self, type):
+        """
+        Return IFC objects filtered by IFC Type and wrapped with the entity_instance class.
+
+        See ifcopenshell.entity_instance for class methods and properties
+        """
         return [entity_instance(e) for e in self.wrapped_data.by_type(type)]
 
     def traverse(self, inst, max_levels=None):
diff --git a/src/ifcopenshell-python/ifcopenshell/geom/main.py b/src/ifcopenshell-python/ifcopenshell/geom/main.py
index adbc53863c..14b1f84827 100644
--- a/src/ifcopenshell-python/ifcopenshell/geom/main.py
+++ b/src/ifcopenshell-python/ifcopenshell/geom/main.py
@@ -136,10 +136,29 @@ class tree(ifcopenshell_wrapper.tree):
             args.append(kwargs.get("completely_within", False))
         if "extend" in kwargs:
             args.append(kwargs.get("extend", -1.e-5))
-        return [entity_instance(e) for e in ifcopenshell_wrapper.tree.select_box(*args)]
-
+        return [entity_instance(e) for e in ifcopenshell_wrapper.tree.select_box(*args)
 
 def create_shape(settings, inst, repr=None):
+    """
+    Return a geometric representation from STEP-based IFCREPRESENTATIONSHAPE
+    or
+    Return an OpenCASCADE BRep if settings.USE_PYTHON_OPENCASCADE == True
+
+    example:
+
+    settings = ifcopenshell.geom.settings()
+    settings.set(settings.USE_PYTHON_OPENCASCADE, True)
+
+    ifc_file = ifcopenshell.open(file_path)
+    products = ifc_file.by_type("IfcProduct")
+
+    for i, product in enumerate(products):
+        if product.Representation is not None:
+            try:
+                shape = geom.create_shape(settings, inst=product).geometry
+                shape_gpXYZ = shape.Location().Transformation().TranslationPart() # These are methods of the TopoDS_Shape class from pythonOCC
+                print(shape_gpXYZ.X(), shape_gpXYZ.Y(), shape_gpXYZ.Z()) # These are methods of the gpXYZ class from pythonOCC
+    """
     return wrap_shape_creation(
         settings,
         ifcopenshell_wrapper.create_shape(