docs: Improve documentation of Testplan.get_percentage

Also, add two error conditions (for fractions that don't make sense).

Signed-off-by: Rupert Swarbrick <rswarbrick@lowrisc.org>

Author: rswarbrick

src/dvsim/testplan.py

@@ -288,12 +288,19 @@ def _create_testplan_elements(kind: str, raw_dicts_list: list, tags: set) -> lis
         return items
 
     @staticmethod
-    def _get_percentage(value, total) -> str:
-        """Returns a string representing percentage upto 2 decimal places."""
-        if total == 0:
-            return "-- %"
-        perc = value / total * 100 * 1.0
-        return f"{round(perc, 2):.2f} %"
+    def _get_percentage(value: int, total: int) -> str:
+        """Format a fraction (value / total) as a float with up to 2 decimal places.
+
+        Both arguments should be non-negative and value should be at most equal
+        to total. If total is zero, this is reported as "-- %".
+
+        """
+        if value > total:
+            raise ValueError("Cannot represent fraction over 100%")
+        if value < 0:
+            raise ValueError("Cannot represent negative fraction")
+
+        return "-- %" if total == 0 else f"{round(100 * value / total, 2):.2f} %"
 
     @staticmethod
     def get_dv_style_css() -> str: