I'll do this. Thanks. btw: this is existing code reformatted. :-)

I completely agree re. your statement on documenting public API types - I've actually stated on other PRs that at an absolutely minimum, the type itself should be documented. I typically document the type before fleshing it out as it helps me be clear on the motivation for it.