update README, break up report cmd func

evennia/contrib/base_systems/ingame_reports/README.md

@@ -41,13 +41,15 @@ Players can submit new reports through the command for each report type, and sta
 
 Players can submit reports using the following commands:
 
-* `bug` - Files a bug report. An optional target can be included, making it easier for devs/builders to track down issues.
-* `report` - Reports a player for inappropriate or rule-breaking behavior. *Requires* a target to be provided - it searches among accounts by default.
-* `idea` - Submits a general suggestion, with no target. It also has an alias of `ideas` which allows you to view all of your submitted ideas.
+* `bug <text>` - Files a bug report. An optional target can be included - `bug <target> = <text>` - making it easier for devs/builders to track down issues.
+* `report <player> = <text>` - Reports a player for inappropriate or rule-breaking behavior. *Requires* a target to be provided - it searches among accounts by default.
+* `idea <text>` - Submits a general suggestion, with no target. It also has an alias of `ideas` which allows you to view all of your submitted ideas.
 
 ### Managing reports
 
-The `manage reports` command allows staff to review and manage the various types of reports. It dynamically aliases itself to include whatever types of reports you've configured for your game - by default, this means it makes `manage bugs`, `manage players`, and `manage ideas` available along with the default `manage reports`.
+The `manage reports` command allows staff to review and manage the various types of reports by launching a management menu.
+
+This command will dynamically add aliases to itself based on the types of reports available, with each command string launching a menu for that particular report type. The aliases are built on the pattern `manage <report type>s` - by default, this means it makes `manage bugs`, `manage players`, and `manage ideas` available along with the default `manage reports`, and that e.g. `manage bugs` will launch the management menu for `bug`-type reports.
 
 Aside from reading over existing reports, the menu allows you to change the status of any given report. By default, the contrib includes two different status tags: `in progress` and `closed`.
 
@@ -66,7 +68,10 @@ INGAME_REPORT_STATUS_TAGS = ('in progress', 'rejected', 'completed')
 
 ### Adding new types of reports
 
-The contrib is designed to make adding new types of reports to the system as simple as possible, requiring only two steps.
+The contrib is designed to make adding new types of reports to the system as simple as possible, requiring only two steps:
+
+1. Update your settings file to include an `INGAME_REPORT_TYPES` setting.
+2. Create and add a new `ReportCmd` to your command set.
 
 #### Update your settings
 

evennia/contrib/base_systems/ingame_reports/reports.py

@@ -41,7 +41,6 @@ from evennia.comms.models import Msg
 
 from . import menu
 
-# TODO: use actual default command class
 _DEFAULT_COMMAND_CLASS = class_from_module(settings.COMMAND_DEFAULT_CLASS)
 
 # the default report types
@@ -155,6 +154,28 @@ class ReportCmdBase(_DEFAULT_COMMAND_CLASS):
         self.hub = hub
         return super().at_pre_cmd()
 
+    def target_search(self, searchterm, **kwargs):
+        """
+        Search for a target that matches the given search term. By default, does a normal search via the
+        caller - a local object search for a Character, or an account search for an Account.
+
+        Args:
+            searchterm (str) - The string to search for
+
+        Returns:
+            result (Object, Account, or None) - the result of the search
+        """
+        return self.caller.search(searchterm)
+
+    def create_report(self, *args, **kwargs):
+        """
+        Creates the report. By default, this creates a Msg with any provided args and kwargs.
+
+        Returns:
+            success (bool) - True if the report was created successfully, or False if there was an issue.
+        """
+        return create.create_message(*args, **kwargs)
+
     def func(self):
         hub = self.hub
         if not self.args:
@@ -169,7 +190,7 @@ class ReportCmdBase(_DEFAULT_COMMAND_CLASS):
 
         target = None
         if target_str:
-            target = self.caller.search(target_str)
+            target = self.target_search(target_str)
             if not target:
                 return
         elif self.require_target:
@@ -180,7 +201,7 @@ class ReportCmdBase(_DEFAULT_COMMAND_CLASS):
         if target:
             receivers.append(target)
 
-        if create.create_message(
+        if self.create_report(
             self.account, message, receivers=receivers, locks=self.report_locks, tags=["report"]
         ):
             # the report Msg was successfully created