Indeed! There's no better documentation than the code itself.
Godoc —the documentation tool for Go— also generates it from the source code.
Concise and clear, here is an example input [1] and its corresponding output [2].
Except for all the things you need to know in order to use the code. Which are why you still write actual real honest-to-God prose documentation. Or, if you don't, is why I don't bother trying to use your code.
This is not specific to godoc. Most, perhaps effectively all (certainly all the ones I've seen and used), automated code generation tools have a place to put arbitrary prose at the top. The fact that it is so often unused is a developer problem, not a tool problem.