Update docstrings, and API doc configuration.

docs/index.rst

@@ -15,11 +15,33 @@ from the `dataclasses` module can be useful to help write
 compact Component classes.
 
 
-The World Class
----------------
- .. autoclass:: esper.World
-    :members:
-
+The World context
+-----------------
+
+.. autofunction:: esper.switch_world
+.. autofunction:: esper.delete_world
+.. autofunction:: esper.list_worlds
+.. autofunction:: esper.create_entity
+.. autofunction:: esper.delete_entity
+.. autofunction:: esper.entity_exists
+.. autofunction:: esper.add_processor
+.. autofunction:: esper.remove_processor
+.. autofunction:: esper.get_processor
+.. autofunction:: esper.component_for_entity
+.. autofunction:: esper.components_for_entity
+.. autofunction:: esper.add_component
+.. autofunction:: esper.remove_component
+.. autofunction:: esper.get_component
+.. autofunction:: esper.get_components
+.. autofunction:: esper.has_component
+.. autofunction:: esper.has_components
+.. autofunction:: esper.try_component
+.. autofunction:: esper.try_components
+.. autofunction:: esper.process
+.. autofunction:: esper.timed_process
+.. autofunction:: esper.clear_database
+.. autofunction:: esper.clear_cache
+.. autofunction:: esper.clear_dead_entities
 
 Events
 ------

esper/__init__.py

@@ -464,11 +464,14 @@ def try_components(entity: int, *component_types: _Type[_C]) -> _Optional[_Tuple
 def clear_dead_entities() -> None:
     """Finalize deletion of any Entities that are marked as dead.
 
-    In the interest of performance, this function duplicates code from the
-    `delete_entity` function. If that function is changed, those changes should
-    be duplicated here as well.
-    This function should be called in main loop after systems.
+    This function is provided for those who are not making use of
+    :py:func:`esper.add_processor` and :py:func:`esper.process`. If you are
+    calling your processors manually, this function should be called in
+    your main loop after calling all processors.
     """
+    # In the interest of performance, this function duplicates code from the
+    # `delete_entity` function. If that function is changed, those changes should
+    # be duplicated here as well.
     for entity in _dead_entities:
 
         for component_type in _entities[entity]:
@@ -532,10 +535,19 @@ def delete_world(name: str) -> None:
 
 
 def switch_world(name: str) -> None:
-    """Switch World contexts.
-
-    This function is used to switch between World contexts.
-    If the named context does not exist, a new one will be created.
+    """Switch to a new World context by name.
+
+    Esper can have one or more "Worlds". Each World is a dedicated
+    context, and does not share Entities, Components, etc. For
+    some game designs, it simplifies things to use a dedicated
+    World for each scene. For other designs, a single World may
+    be sufficient. This function will allow you to create and
+    switch between as many World contexts as required. If the
+    requested name does not exist, a new context is created
+    automatically with that name.
+
+    .. note:: At startup, a "default" context exists, and is
+              already active.
     """
     if name not in _context_map:
         # Create a new