Clean up subroutine documentation; mostly formatting changes, with
some new content.

Signed-off-by: Linas Vepstas <linas@austin.ibm.com>
Signed-off-by: Paul Mackerras <paulus@samba.org>