docs update

Author: forman

chartlets.py/chartlets/contribution.py

@@ -6,6 +6,18 @@
 
 
 class Contribution(ABC):
+    """Base class for specific application contributions.
+
+    Derived classes typically add attributes that allow
+    customizing the appearance of the contribution in the
+    user interface. The user-provided values for such
+    attributes determine the initial state of the
+    contribution when it is rendered for the first time.
+
+    Args:
+        name: A name that should be unique within an extension.
+        initial_state: contribution specific attribute values.
+    """
     # noinspection PyShadowingBuiltins
     def __init__(self, name: str, **initial_state):
         self.name = name
@@ -15,6 +27,9 @@ def __init__(self, name: str, **initial_state):
         self.callbacks: list[Callback] = []
 
     def to_dict(self) -> dict[str, Any]:
+        """Convert this contribution into a
+        JSON serializable dictionary.
+        """
         d = dict(name=self.name)
         if self.initial_state is not None:
             d.update(initialState=self.initial_state)
@@ -27,7 +42,31 @@ def to_dict(self) -> dict[str, Any]:
         return d
 
     def layout(self, *args) -> Callable:
-        """Decorator."""
+        """A decorator for a user-provided function that
+        returns the initial user interface layout.
+
+        The decorated function must return an instance of
+        a `chartlets.Component`, usually a `chartlets.components.Box`
+        that arranges other components in some layout.
+
+        The first parameter of the decorated function must be a
+        positional argument. It provides an application-specific
+        context that is used to allow for access server-side
+        configuration and resources. The parameter should be
+        called `ctx`.
+
+        Other parameters of the decorated function are user-defined
+        and must have a corresponding `chartlets.Input` argument
+        in the `layout` decorator in the same order.
+
+        Args:
+            args: Instances of the `chartlets.Input` class that
+                define the source of the value for the corresponding
+                parameter of the decorated function. Optional.
+
+        Returns:
+             The decorated, user-provided function.
+        """
 
         def decorator(function: Callable) -> Callable:
             self.layout_callback = Callback.from_decorator(

docs/usage.md

@@ -1,4 +1,4 @@
-The Chartlets framework has two types of users:
+The Chartlets framework has two types of target users:
 
 - **Application contributors** develop new contributions 
   for a specific web application that is powered by Chartlets.