add doc comments for functions

[stonylohr]

Many functions have stub doc comments (///), but more detail would be preferable. The C++ code typically includes expansive comments and could be a good source to start from.

I have not yet explored annotation syntax for rust doc comments, so I'm unsure how much conversion would be needed when copying doc comments from c++ or other geographic lib counterparts.

[michaelkirk]

This would be excellent!