Currently we have 3 places where we generate a doc comment, and each of
these does it differently.

With this they now generate the comments the same way. The doc comment
generator functions are documented with the invariants, namely that they
never return an empty string and the output is always trimmed (i.e. no
trailing whitespace).

…omments