Fix description in updated dice roller contrib. Resolve #3207

docs/source/Contribs/Contrib-Dice.md

@@ -34,7 +34,7 @@ class CharacterCmdSet(default_cmds.CharacterCmdSet):
     > roll 1d20
     > roll 1d20 - 4
 
-The result of the roll will be echoed to the room
+The result of the roll will be echoed to the room.
 
 One can also specify a standard Python operator in order to specify
 eventual target numbers and get results in a fair and guaranteed
@@ -55,27 +55,12 @@ Is a hidden roll that does not inform the room it happened.
 
 ## Rolling dice from code
 
-To roll dice in code, use the `roll` function from this module. It has two
-main ways to define the expected roll:
-
-```python
-from evennia.contrib.rpg.dice import roll
-
-roll(dice, dicetype=6, modifier=None, conditional=None, return_tuple=False,
-      max_dicenum=10, max_dicetype=1000)
-
-```
-
-You can only roll one set of dice. If your RPG requires you to roll multiple
-sets of dice and combine them in more advanced ways, you can do so with multiple
-`roll()` calls.
-
-### Roll dice based on a string
-
 You can specify the first argument as a string on standard RPG d-syntax (NdM,
 where N is the number of dice to roll, and M is the number sides per dice):
 
 ```python
+from evennia.contrib.rpg.dice import roll
+
 roll("3d10 + 2")
 ```
 
@@ -85,14 +70,17 @@ You can also give a conditional (you'll then get a `True`/`False` back):
 roll("2d6 - 1 >= 10")
 ```
 
-### Explicit arguments
-
 If you specify the first argument as an integer, it's interpret as the number of
 dice to roll and you can then build the roll more explicitly. This can be
 useful if you are using the roller together with some other system and want to
 construct the roll from components.
 
 
+```python
+roll(dice, dicetype=6, modifier=None, conditional=None, return_tuple=False,
+      max_dicenum=10, max_dicetype=1000)
+```
+
 Here's how to roll `3d10 + 2` with explicit syntax:
 
 ```python
@@ -105,6 +93,10 @@ Here's how to roll `2d6 - 1 >= 10` (you'll get back `True`/`False` back):
 roll(2, 6, modifier=("-", 1), conditional=(">=", 10))
 ```
 
+You can only roll one set of dice. If your RPG requires you to roll multiple
+sets of dice and combine them in more advanced ways, you can do so with multiple
+`roll()` calls.
+
 ### Get all roll details
 
 If you need the individual rolls (e.g. for a dice pool), set the `return_tuple` kwarg:

evennia/contrib/rpg/dice/README.md

@@ -34,7 +34,7 @@ class CharacterCmdSet(default_cmds.CharacterCmdSet):
     > roll 1d20
     > roll 1d20 - 4
 
-The result of the roll will be echoed to the room
+The result of the roll will be echoed to the room.
 
 One can also specify a standard Python operator in order to specify
 eventual target numbers and get results in a fair and guaranteed
@@ -55,27 +55,12 @@ Is a hidden roll that does not inform the room it happened.
 
 ## Rolling dice from code
 
-To roll dice in code, use the `roll` function from this module. It has two
-main ways to define the expected roll:
-
-```python
-from evennia.contrib.rpg.dice import roll
-
-roll(dice, dicetype=6, modifier=None, conditional=None, return_tuple=False,
-      max_dicenum=10, max_dicetype=1000)
-
-```
-
-You can only roll one set of dice. If your RPG requires you to roll multiple
-sets of dice and combine them in more advanced ways, you can do so with multiple
-`roll()` calls.
-
-### Roll dice based on a string
-
 You can specify the first argument as a string on standard RPG d-syntax (NdM,
 where N is the number of dice to roll, and M is the number sides per dice):
 
 ```python
+from evennia.contrib.rpg.dice import roll
+
 roll("3d10 + 2")
 ```
 
@@ -85,14 +70,17 @@ You can also give a conditional (you'll then get a `True`/`False` back):
 roll("2d6 - 1 >= 10")
 ```
 
-### Explicit arguments
-
 If you specify the first argument as an integer, it's interpret as the number of
 dice to roll and you can then build the roll more explicitly. This can be
 useful if you are using the roller together with some other system and want to
 construct the roll from components.
 
 
+```python
+roll(dice, dicetype=6, modifier=None, conditional=None, return_tuple=False,
+      max_dicenum=10, max_dicetype=1000)
+```
+
 Here's how to roll `3d10 + 2` with explicit syntax:
 
 ```python
@@ -105,6 +93,10 @@ Here's how to roll `2d6 - 1 >= 10` (you'll get back `True`/`False` back):
 roll(2, 6, modifier=("-", 1), conditional=(">=", 10))
 ```
 
+You can only roll one set of dice. If your RPG requires you to roll multiple
+sets of dice and combine them in more advanced ways, you can do so with multiple
+`roll()` calls.
+
 ### Get all roll details
 
 If you need the individual rolls (e.g. for a dice pool), set the `return_tuple` kwarg:

evennia/contrib/rpg/dice/dice.py

@@ -33,7 +33,7 @@ from evennia.contrib.rpg import dice  <---
 
 class CharacterCmdSet(default_cmds.CharacterCmdSet):
     # ...
-    def at_object_creation(self):
+    def at_cmdset_creation(self):
         # ...
         self.add(dice.CmdDice())  # <---
 
@@ -45,15 +45,16 @@ class CharacterCmdSet(default_cmds.CharacterCmdSet):
 
 To roll dice in code, use the `roll` function from this module:
 
-```python
+    from evennia.contrib.rpg import dice
 
-from evennia.contrib.rpg import dice
-dice.roll(3, 10, ("+", 2))  # 3d10 + 2
-```
+    dice.roll("3d10 + 2")
 
-or use the string syntax:
 
-dice.roll("3d10 + 2")
+If your system generates the dice dynamically you can also enter each part
+of the roll separately:
+
+    dice.roll(3, 10, ("+", 2))  # 3d10 + 2
+
 
 """
 import re
@@ -113,6 +114,14 @@ def roll(
 
     Examples:
         ::
+            # string form
+            print roll("3d6 + 2")
+            10
+            print roll("2d10 + 2 > 10")
+            True
+            print roll("2d20 - 2 >= 10")
+            (8, False, 2, (4, 6)) # roll was 4 + 6 - 2 = 8
+
             # explicit arguments
             print roll(2, 6) # 2d6
             7
@@ -125,14 +134,6 @@ def roll(
             print roll(2, 20, ('-', 2), conditional=('>=', 10), return_tuple=True)
             (8, False, 2, (4, 6)) # roll was 4 + 6 - 2 = 8
 
-            # string form
-            print roll("3d6 + 2")
-            10
-            print roll("2d10 + 2 > 10")
-            True
-            print roll("2d20 - 2 >= 10")
-            (8, False, 2, (4, 6)) # roll was 4 + 6 - 2 = 8
-
     """
 
     modifier_string = ""