Clean up subroutine documentation; mostly formatting changes, with
some new content.
Signed-off-by: NLinas Vepstas <linas@austin.ibm.com>
Signed-off-by: NPaul Mackerras <paulus@samba.org>