Comment cleanups to improve generated docs

- added comments to fields which didn't have any.
- changed all `//` comments to the new format
- fixed indents/line lengths/style on lines I touched
For the secondary/supplimentary alignment flags, it might be preferable to define secondary/supplimentary instead of referring people to the SAM/BAM spec, as these two fields are oft confused.