Document GlobalStack

cura/Settings/GlobalStack.py

@@ -18,6 +18,8 @@ from UM.Settings.Interfaces import ContainerInterface
 from . import Exceptions
 from .CuraContainerStack import CuraContainerStack
 
+##  Represents the Global or Machine stack and its related containers.
+#
 class GlobalStack(CuraContainerStack):
     def __init__(self, container_id: str, *args, **kwargs):
         super().__init__(container_id, *args, **kwargs)
@@ -31,11 +33,20 @@ class GlobalStack(CuraContainerStack):
         # if the resolve function tried to access the same property it is a resolve for.
         self._resolving_settings = set()
 
+    ##  Get the list of extruders of this stack.
+    #
+    #   \return The extruders registered with this stack.
     @pyqtProperty("QVariantList")
     def extruders(self) -> list:
         return self._extruders
 
-    def addExtruder(self, extruder):
+    ##  Add an extruder to the list of extruders of this stack.
+    #
+    #   \param extruder The extruder to add.
+    #
+    #   \throws Exceptions.TooManyExtrudersError Raised when trying to add an extruder while we
+    #                                            already have the maximum number of extruders.
+    def addExtruder(self, extruder: ContainerStack) -> None:
         extruder_count = self.getProperty("machine_extruder_count", "value")
         if extruder_count and len(self._extruders) + 1 > extruder_count:
             raise Exceptions.TooManyExtrudersError("Tried to add extruder to {id} but its extruder count is {count}".format(id = self.id, count = extruder_count))
@@ -43,6 +54,16 @@ class GlobalStack(CuraContainerStack):
         self._extruders.append(extruder)
 
     ##  Overridden from ContainerStack
+    #
+    #   This will return the value of the specified property for the specified setting,
+    #   unless the property is "value" and that setting has a "resolve" function set.
+    #   When a resolve is set, it will instead try and execute the resolve first and
+    #   then fall back to the normal "value" property.
+    #
+    #   \param key The setting key to get the property of.
+    #   \param property_name The property to get the value of.
+    #
+    #   \return The value of the property for the specified setting, or None if not found.
     @override(ContainerStack)
     def getProperty(self, key: str, property_name: str) -> Any:
         if not self.definition.findDefinitions(key = key):
@@ -58,10 +79,16 @@ class GlobalStack(CuraContainerStack):
         return super().getProperty(key, property_name)
 
     ##  Overridden from ContainerStack
+    #
+    #   This will simply raise an exception since the Global stack cannot have a next stack.
     @override(ContainerStack)
     def setNextStack(self, next_stack: ContainerStack) -> None:
         raise Exceptions.InvalidOperationError("Global stack cannot have a next stack!")
 
+    # protected:
+
+    # Determine whether or not we should try to get the "resolve" property instead of the
+    # requested property.
     def _shouldResolve(self, key: str, property_name: str) -> bool:
         if property_name is not "value":
             # Do not try to resolve anything but the "value" property