Improve docstrings

src/formulaic_contrasts/_contrasts.py

@@ -33,14 +33,24 @@ def cond(self, **kwargs):
         """
         Get a contrast vector representing a specific condition.
 
+        The `kwargs` are key/value pairs where the key refers to a variable used in the
+        design and the value represents a category of that variable. Variables not specified
+        will be filled with their default/baseline value.
+
+        The vectors generated by `.cond` can be combined using standard arithmetic operations
+        to obtain the desired contrast, e.g.
+
+        >>> contrast = model.cond(treatment="drugA") - model.cond(treatment="placebo")
+
         Parameters
         ----------
         **kwargs
             column/value pairs.
 
         Returns
         -------
-            A contrast vector that aligns to the columns of the design matrix.
+        A vector with one element per column in the design matrix,
+        where the kwargs arguments are coded as in the design matrix.
         """
         cond_dict = kwargs
         if not set(cond_dict.keys()).issubset(self.variables):
@@ -60,6 +70,9 @@ def contrast(self, column, baseline, group_to_compare):
         """
         Build a simple contrast for pairwise comparisons.
 
+        For more complex contrasts, please use construct a contrast vector using
+        :func:`~formulaic_contrasts.FormulaicContrasts.cond`.
+
         Parameters
         ----------
         column