Move some comments to doxygen

We have very nice comments equally nicely buried. This patch is to unbury them. Given the amount of code change (nothing) and the usefulness (now you can read these comments on the relevant api.drupal.org page) I dared to RTBC this immediately. The icing on the cake: I added missing doxygen to one omment_render.