doc: Add documentation to the Result class in testplan.py

[rswarbrick]

In particular, this gives types to all the arguments and gives units for the numbers (I had to run some tests to check what they were!)

[AlexJones0]

Thanks @rswarbrick!

[AlexJones0]

One suggestion I might have would be to make most of the arguments here keyword-only:

Suggested change

	def __init__(
	self,
	name: str,
	passing: int = 0,
	total: int = 0,
	job_runtime: float | None = None,
	simulated_time: float | None = None,
	) -> None:
	def __init__(
	self,
	name: str,
	*
	passing: int = 0,
	total: int = 0,
	job_runtime: float | None = None,
	simulated_time: float | None = None,
	) -> None:

This is because currently you can make a Result like:

Result("example test", 3, 5, 19.20, 13.41)

which isn't particularly descriptive to read, so you need to search through the definition. This change would instead mean you need to write:

Result("example test", passing=3, total=5, job_runtime=19.20, simulated_time=13.41)

I'll leave it up to you whether you prefer that or not though.

[AlexJones0]

It doesn't need to be changed in this PR (as I appreciate it would be a widespread change across the code base) - but IMO these parameters should be suffixed by their units (e.g. job_runtime_s and simulated_time_us) to avoid the confusion entirely.

[AlexJones0]

Another nice idea might be to add setters for passing and total to this class to enforce this invariant and error otherwise - but I appreciate that's probably outside of the scope of the improvements in this PR, which is just doing some cleanup.