I rather like the lack of markup in godoc. I think there should be a wee bit more than it currently has (lack of lists and headers springs to mind), but that's

I rather like the lack of markup in godoc. I think there should be a wee bit more than it currently has (lack of lists and headers springs to mind), but that's about it. There's a proposal to add this, btw [1] I certainly dislike stuff such as: // Basename returns the last portion of the path (that is, everything // after the last / or \, depending on the platform). // // @param path string The pathname to modify. // @return string The modified pathname. func Basename(path string) string Which almost invariable ends up happening; the usual way this happens is something along the lines of "there is not enough documentation!", "I know, let's add a linter to enforce it!", useless documentation ensues. Writing stuff as prose rather than a "bullet-list" in general is also better, IMO. I often find "structured" documentation like this much more sloppy in practice, as too often people will just slap on some @-things and confuse that for "documentation". Writing one or two paragraphs is often clearer. [1]: https://github.com/golang/go/discussions/48305 https://github.com/golang/go/discussions/48305