This is nice and ok in C. You provide doxy info how to use the function and in addition you comment scopes and important calls. In C++ function names would be much easier to read and as such the function wouldn't need this much inner commenting.

Edit:
Here a not-so-clean example of my code; Criticism welcome.
http://awake.svn.sourceforge.net/viewvc/awake/trunk/AwakeEngine/AwakeMain/include/AwEngine.h
http://awake.svn.sourceforge.net/viewvc/awake/trunk/AwakeEngine/AwakeMain/src/AwEngine.cpp