Add docstrings, examples #17
Description
There's been a few comments where having concrete examples would help explain what's covered/not covered by the API.
What would be a good way to document such examples?
I'm OK with getting this in, but note that much seems implicitly defined by typing. I'm not at all an expert on this, but there are oddities:
What does Quantity[V, U, D] mean? Is it now required for Quantity to be (partially) defined by a Dimension? Or is that still optional. I can see the point of Dimension, but astropy's Quantity makes clear one can get a nice working system without it.
I don't understand the typing for the operators: the typing suggests that other is required to be a Quantity, but surely that is incorrect. At least, I'd assume we want q * 5 to work, and probably dimensionless_q + 10. as well).
I guess the second option brings up an overall worry with most PRs so far: we've jumped straight into abstractions, but I at least work by far the best with concrete examples. Comments and docstrings would seem appropriate!
I'd assume we want q * 5 to work
Yes, perhaps we want to expand
self: "Quantity[V, U, D]", other: "Quantity[op.CanRMul[V, R], U, D]"
to
self: "Quantity[V, U, D]", other: "Quantity[op.CanRMul[V, R], U, D] | op.CanRMul[V, R]"
@lucascolley - seems sensible for multiplication. What about the example I gave for addition? Here, unfortunately, it does depend on the unit instance, not the type... I guess the question boils down to whether, generically, any V is treated as equivalent to a dimensionless quantity.
Note that in astropy there is an exception to this: we special-case zero as equivalent to 0 with any unit, so that q < 0 always works (same for inf and -inf). Is this even expressible in typing?
Note that perhaps both the above should be restricted - I've been arguing elsewhere for not pre-allowing flexibility or baking in complexity. So, if some other unit libraries do not support adding non-quantities to dimensionless ones, or do not allow comparing with 0, then that's fine. Ideally, though, the documents that we produce explicitly state that support for examples like the ones above is not required.
Agreed. Generalizing non-Quantities to Quantities is challenging and may be best left as a choice for implementing libraries. The common API of course is for Q2Q ops to work!