api: add proper doxygen comments to C++ headers and normalise doc

Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>

examples/c++/Pwm3-cycle.cpp

@@ -40,6 +40,8 @@ sig_handler(int signo)
 
 int main ()
 {
+    signal(SIGINT, sig_handler);
+//! [Interesting]
     maa::Pwm* pwm;
 
     pwm = new maa::Pwm(3);
@@ -48,8 +50,6 @@ int main ()
     }
     fprintf(stdout, "Cycling PWM on IO3 (pwm3) \n");
 
-    signal(SIGINT, sig_handler);
-
     float value = 0.0f;
     while (running == 0) {
         value = value + 0.01f;
@@ -60,6 +60,7 @@ int main ()
         }
     }
     delete pwm;
+//! [Interesting]
 
     return MAA_SUCCESS;
 }