Expand prototype inheritance docs. Resolve #2220.

docs/source/Components/Prototypes.md

@@ -74,11 +74,9 @@ before running.
 
 All keys starting with `prototype_` are for book keeping.
 
- - `prototype_key` - the 'name' of the prototype. While this can sometimes be skipped (such as when
-    defining a prototype in a module or feeding a prototype-dict manually to the spawner function),
-it's good
-    practice to try to include this. It is used for book-keeping and storing of the prototype so you
-    can find it later.
+ - `prototype_key` - the 'name' of the prototype, used for referencing the prototype
+    when spawning and inheritance. If defining a prototype in a module and this
+    not set, it will be auto-set to the name of the prototype's variable in the module.
  - `prototype_parent` - If given, this should be the `prototype_key` of another prototype stored in
     the system or available in a module. This makes this prototype *inherit* the keys from the
     parent and only override what is needed. Give a tuple `(parent1, parent2, ...)` for multiple
@@ -90,6 +88,7 @@ it's good
    the copying and editing of the prototype when loaded through the OLC. The second determines who
    may use the prototype to create new objects.
 
+
 The remaining keys determine actual aspects of the objects to spawn from this prototype:
 
  - `key` - the main object identifier. Defaults to "Spawned Object *X*", where *X* is a random
@@ -111,15 +110,28 @@ exist.
  - `attrs` - list of [Attributes](./Attributes.md). These are given as tuples `(attrname, value,
 category, lockstring)`
  - Any other keywords are interpreted as non-category [Attributes](./Attributes.md) and their values.
-This is
-   convenient for simple Attributes - use `attrs` for full control of Attributes.
+This is convenient for simple Attributes - use `attrs` for full control of Attributes.
 
-Deprecated as of Evennia 0.8:
+#### More on prototype inheritance
 
- - `ndb_<name>` - sets the value of a non-persistent attribute (`"ndb_"` is stripped from the name).
-   This is simply not useful in a prototype and is deprecated.
- - `exec` - This accepts a code snippet or a list of code snippets to run. This should not be used -
-   use callables or [$protfuncs](./Prototypes.md#protfuncs) instead (see below).
+- A prototype can inherit by defining a `prototype_parent` pointing to the name
+  (`prototype_key` of another prototype). If a list of `prototype_keys`, this
+  will be stepped through from left to right, giving priority to the first in
+  the list over those appearing later. That is, if your inheritance is
+  `prototype_parent = ('A', 'B,' 'C')`, and all parents contain colliding keys,
+  then the one from `A` will apply.
+- The prototype keys that start with `prototype_*` are all unique to each
+  prototype. They are _never_ inherited from parent to child.
+- The prototype fields `'attr': [(key, value, category, lockstring),...]`
+  and `'tags': [(key, category, data), ...]` are inherited in a _complementary_
+  fashion. That means that only colliding key+category matches will be replaced, not the entire list.
+  Remember that the category `None` is also considered a valid category!
+- Adding an Attribute as a simple `key:value` will under the hood be translated
+  into an Attribute tuple `(key, value, None, '')` and may replace an Attribute
+  in the parent if it the same key  and a `None` category.
+- All other keys (`permissions`, `destination`, `aliases` etc) are completely
+  _replaced_ by the child's value if given. For the parent's value to be
+  retained, the child must not define these keys at all.
 
 ### Prototype values
 

evennia/prototypes/prototypes.py

@@ -49,7 +49,6 @@ _PROTOTYPE_RESERVED_KEYS = _PROTOTYPE_META_NAMES + (
     "destination",
     "permissions",
     "locks",
-    "exec",
     "tags",
     "attrs",
 )