Implement the suggestions by @tgoodlet

Author: obestwalter

docs/examples/eggsample-spam/eggsample_spam.py

@@ -6,7 +6,7 @@ def eggsample_add_ingredients(ingredients):
         ingredients.remove("egg")
     spam = ["lovely spam", "wonderous spam", "splendiferous spam"]
     print(f"Add {spam}")
-    ingredients.extend(spam)
+    return spam
 
 @eggsample.hookimpl
 def eggsample_prep_condiments(condiments):

docs/examples/eggsample/eggsample/host.py

@@ -6,13 +6,16 @@
 
 condiments_tray = {"pickled walnuts": 13, "steak sauce": 4, "mushy peas": 2}
 
-class EggselentCook:
+class EggsellentCook:
     def __init__(self, hook):
         self.hook = hook
         self.ingredients = []
 
     def add_ingredients(self):
-        self.hook.eggsample_add_ingredients(ingredients=self.ingredients)
+        more_ingredients = self.hook.eggsample_add_ingredients(
+            ingredients=self.ingredients)
+        # each hook implementation returned a list of ingredients
+        self.ingredients.extend(more_ingredients)
 
     def prepare_the_food(self):
         random.shuffle(self.ingredients)
@@ -27,7 +30,7 @@ def main():
     pluginmanager.add_hookspecs(hookspecs)
     pluginmanager.load_setuptools_entrypoints("eggsample")
     pluginmanager.register(lib)
-    cook = EggselentCook(pluginmanager.hook)
+    cook = EggsellentCook(pluginmanager.hook)
     cook.add_ingredients()
     cook.prepare_the_food()
     cook.serve_the_food()

docs/examples/eggsample/eggsample/lib.py

@@ -4,7 +4,7 @@
 def eggsample_add_ingredients(ingredients):
     basics = ["egg", "egg", "salt", "pepper"]
     print(f"Add {basics}")
-    ingredients.extend(basics)
+    return basics
 
 @eggsample.hookimpl
 def eggsample_prep_condiments(condiments):

docs/index.rst

@@ -34,9 +34,9 @@ avoid unnecessary exposure of state and behaviour. This leads to a more
 between ``host`` and ``plugins``.
 
 The ``pluggy`` approach puts the burden on the designer of the
-``host program`` to think carefully about which objects are explicitly needed
-by an implementation and gives designers of the ``plugin`` a clear framework
-for how to extend the ``host`` by giving them a well defined set of functions
+``host program`` to think carefully about which objects are really
+needed in a hook implementation, which gives `plugin` creators a clear
+framework for how to extend the ``host`` via a well defined set of functions
 and objects to work with.
 
 How does it work?
@@ -46,7 +46,7 @@ Let us start with a short overview of what is involved:
 * ``host`` or ``host program``: the program offering extensibility
   by specifying ``hook functions`` and invoking their implementation(s) as
   part of program execution
-* ``plugin``: the program implementing a subset of the specified hooks and
+* ``plugin``: the program implementing (a subset of) the specified hooks and
   participating in program execution when the implementations are invoked
   by the ``host``
 * ``pluggy``: connects ``host`` and ``plugins`` by using ...