[bluGill]

Missing is one other style of comment: how to use this API. This is not targeted at someone understanding or maintaining the code, but someone outside who just knows (or suspects) they want to use your API without understanding it. While this need not be with the code it generally is better that way because tools can extract information from the code (the comment is before the function foo, therefore it must be about foo, foo takes some parameters with some types - we can link to the documentation for those types...).

This style of comment is only needed if you expect your code to have users who are external and thus don't want to look into the details.