Add TagCategoryProperty.

docs/source/Components/Tags.md

@@ -12,18 +12,26 @@ obj.tags.get("mytag", category="foo")
 ```
 
 ```{code-block} python
-:caption: In code, using TagProperty (auto-assign tag to all instances of the class)
+:caption: In code, using TagProperty or TagCategoryProperty
 
 from evennia import DefaultObject
-from evennia import TagProperty
+from evennia import TagProperty, TagCategoryProperty
+
 class Sword(DefaultObject): 
+    # name of property is the tagkey, category as argument
     can_be_wielded = TagProperty(category='combat')
     has_sharp_edge = TagProperty(category='combat')
 
+    # name of property is the category, tag-keys are arguments
+    damage_type = TagCategoryProperty("piercing", "slashing")
+    crafting_element = TagCategory("blade", "hilt", "pommel") 
+        
 ```
 
 _Tags_ are short text lables one can 'hang' on objects in order to organize, group and quickly find out their properties. An Evennia entity can be tagged by any number of tags. They are more efficient than [Attributes](./Attributes.md) since on the database-side, Tags are _shared_ between all objects with that particular tag. A tag does not carry a value in itself; it either sits on the entity 
 
+You manage Tags using the `TagHandler` (`.tags`) on typeclassed entities. You can also assign Tags on the class level through the `TagProperty` (one tag, one category per line) or the `TagCategoryProperty` (one category, multiple tags per line). Both of these use the `TagHandler` under the hood, they are just convenient ways to add tags already when you define your class. 
+
 Above, the tags inform us that the `Sword` is both sharp and can be wielded. If that's all they do, they could just be a normal Python flag. When tags become important is if there are a lot of objects with different combinations of tags. Maybe you have a magical spell that dulls _all_ sharp-edged objects in the castle - whether sword, dagger, spear or kitchen knife! You can then just grab all objects with the `has_sharp_edge` tag. 
 Another example would be a weather script affecting all rooms tagged as `outdoors` or finding all characters tagged with `belongs_to_fighter_guild`. 
 
@@ -35,34 +43,24 @@ In Evennia, Tags are technically also used to implement `Aliases` (alternative n
 
 Tags are *unique*. This means that there is only ever one Tag object with a given key and category.
 
-> Not specifying a category (default) gives the tag a category of `None`, which is also considered a
-unique key + category combination.
+```{important}
+Not specifying a category (default) gives the tag a category of `None`, which is also considered a unique key + category combination. You cannot use `TagCategoryProperty` to set Tags with `None` categories, since the property name may not be `None`. Use the `TagHandler` (or `TagProperty`) for this.
 
-When Tags are assigned to game entities, these entities are actually sharing the same Tag. This
-means that Tags are not suitable for storing information about a single object - use an
+```
+When Tags are assigned to game entities, these entities are actually sharing the same Tag. This means that Tags are not suitable for storing information about a single object - use an
 [Attribute](./Attributes.md) for this instead. Tags are a lot more limited than Attributes but this also
 makes them very quick to lookup in the database - this is the whole point.
 
 Tags have the following properties, stored in the database:
 
 - **key** - the name of the Tag. This is the main property to search for when looking up a Tag.
-- **category** - this category allows for retrieving only specific subsets of tags used for
-different purposes. You could have one category of tags for "zones", another for "outdoor
-locations", for example. If not given, the category will be `None`, which is also considered a
-separate, default, category.
-- **data** - this is an optional text field with information about the tag. Remember that Tags are
-shared between entities, so this field cannot hold any object-specific information. Usually it would
-be used to hold info about the group of entities the Tag is tagging - possibly used for contextual
-help like a tool tip. It is not used by default.
+- **category** - this category allows for retrieving only specific subsets of tags used for different purposes. You could have one category of tags for "zones", another for "outdoor locations", for example. If not given, the category will be `None`, which is also considered a separate, default, category.
+- **data** - this is an optional text field with information about the tag. Remember that Tags are shared between entities, so this field cannot hold any object-specific information. Usually it would be used to hold info about the group of entities the Tag is tagging - possibly used for contextual help like a tool tip. It is not used by default.
 
-There are also two special properties. These should usually not need to be changed or set, it is
-used internally by Evennia to implement various other uses it makes of the `Tag` object:
-- **model** - this holds a *natural-key* description of the model object that this tag deals with,
-on the form *application.modelclass*, for example `objects.objectdb`. It used by the TagHandler of
-each entity type for correctly storing the data behind the  scenes.
-- **tagtype** - this is a "top-level category" of sorts for the inbuilt children of Tags, namely
-*Aliases* and *Permissions*. The Taghandlers using this special field are especially intended to
-free up the *category* property for any use you desire.
+There are also two special properties. These should usually not need to be changed or set, it is used internally by Evennia to implement various other uses it makes of the `Tag` object:
+
+- **model** - this holds a *natural-key* description of the model object that this tag deals with, on the form *application.modelclass*, for example `objects.objectdb`. It used by the TagHandler of each entity type for correctly storing the data behind the  scenes.
+- **tagtype** - this is a "top-level category" of sorts for the inbuilt children of Tags, namely *Aliases* and *Permissions*. The Taghandlers using this special field are especially intended to free up the *category* property for any use you desire.
 
 ### Adding/Removing Tags
 
@@ -157,6 +155,5 @@ used in the same way as Tags above:
     all_aliases = boy.aliases.all()
 ```
 
-and so on. Similarly to how `@tag` works in-game, there is also the `@perm` command for assigning
-permissions and `@alias` command for aliases.
+and so on. Similarly to how `tag` works in-game, there is also the `perm` command for assigning permissions and `@alias` command for aliases.