Nixpkgs function documentation is rendered using nixdoc. (Which is something else than nix-doc.)
@mightyiam a good first issue would be rendering the first comment from a file at the top of the section. I added it to the documentation team agenda.
We encountered it with @infinisil while hacking on @roberth’s source combinators pull request.