Minor documentation tweaks

src/ifcopenshell-python/ifcopenshell/api/aggregate/assign_object.py

@@ -26,9 +26,28 @@ class Usecase:
     def __init__(self, file, product=None, relating_object=None):
         """Assigns an object as an aggregate to a product
 
-        :param product: The part of the aggregate
-        :param relating_object: The whole of the aggregate
-        :return: entity: The aggregate relationship
+        Typically used when you want to describe how large spaces are made up of
+        smaller spaces. For example large spatial elements (e.g. sites,
+        buidings) can be made out of smaller spatial elements (e.g. storeys,
+        spaces).
+
+        The other common usecase is when larger physical products are made up of
+        smaller physical products. For example, a stair might be made out of a
+        flight, a landing, a railing and so on. Or a wall might be made out of
+        stud members, and coverings.
+
+        IFC placements follow a convention where the placement is relative to
+        its parent in the spatial hierarchy. If your product has a placement,
+        its placement will be recalculated to follow this convention.
+
+        :param product: The part of the aggregate, typically an IfcElement or
+            IfcSpatialStructureElement subclass
+        :type product: ifcopenshell.entity_instance
+        :param relating_object: The whole of the aggregate, typically an
+            IfcElement or IfcSpatialStructureElement subclass
+        :type relating_object: ifcopenshell.entity_instance
+        :return: The IfcRelAggregate relationship instance
+        :rtype: ifcopenshell.entity_instance.entity_instance
 
         Example::
 

src/ifcopenshell-python/ifcopenshell/api/project/create_file.py

@@ -1,6 +1,4 @@
 # IfcOpenShell - IFC toolkit and geometry engine
-# Copyright (C) 2021 Dion Moult <dion@thinkmoult.com>
-#
 # This file is part of IfcOpenShell.
 #
 # IfcOpenShell is free software: you can redistribute it and/or modify
@@ -22,12 +20,22 @@ import ifcopenshell
 
 class Usecase:
     def __init__(self, version: str = "IFC4"):
-        """Create File
+        """Create a blank IFC model file object
 
-        Create a new IFC file object
+        Create a new IFC file object based on the nominated schema version. The
+        schema version you choose determines what type of IFC data you can store
+        in this model. The file is blank and contains no entities.
 
-        :param version: The schema version of the IFC file. Choose from "IFC2X3" or "IFC4".
-        :return: file: The created IFC file object.
+        It also sets up header data for STEP file serialisation, such as the
+        current timestamp, IfcOpenShell as the preprocessor, and defaults to a
+        DesignTransferView MVD.
+
+        :param version: The schema version of the IFC file. Choose from
+            "IFC2X3", "IFC4", or "IFC4X3". If you have loaded in a custom
+            schema, you may specify that schema identifier here too.
+        :type version: str, optional
+        :return: The created IFC file object.
+        :rtype: ifcopenshell.file.file
         """
         self.settings = {"version": version}