Improve some commenting

In preparation for adding apple-docs, improve some comments
in header files.