diff --git a/Common/gmsh.cpp b/Common/gmsh.cpp
index 4e906edc2d71b4d19c0fc5c1a70ac6bab930b82f..0e9eb8082bfa5a7e32d8d5a787d30fbbbf862136 100644
--- a/Common/gmsh.cpp
+++ b/Common/gmsh.cpp
@@ -59,7 +59,12 @@ int gmshInitialize(int argc, char **argv)
 int gmshFinalize()
 {
   if(!isInitialized()) return -1;
-  return !GmshFinalize();
+  if(GmshFinalize()){
+    _initialized = 0;
+    return 0;
+  }
+  Msg::Error("Something went wrong when finalizing Gmsh");
+  return 1;
 }
 
 int gmshOpen(const std::string &fileName)
diff --git a/demos/api/t1.cpp b/demos/api/t1.cpp
index e9643b0e0daae76a6b609365e9666d368185275f..e0a848fc2aaa2e029e8b71f84285ff26b8067004 100644
--- a/demos/api/t1.cpp
+++ b/demos/api/t1.cpp
@@ -1,4 +1,3 @@
-
 // This reimplements gmsh/tutorial/t1.geo in C++. For all the elementary
 // explanations about the general philosphy of entities in Gmsh, see the
 // comments in the .geo file. Comments here will focus on the specifics of the
@@ -64,12 +63,17 @@ int main(int argc, char **argv)
   // entity.
   gmshModelSetPhysicalName(2, 6, "My surface");
 
+  // Before it can be meshed, the internal CAD representation (here in the
+  // built-in "Geo" CAD kernel) must be synchronized with the Gmsh model, which
+  // will create the relevant Gmsh data structure to represent the full topology
+  // of the model. This is achieved by the gmshModelGeoSynchronize() API call.
   gmshModelGeoSynchronize();
 
+  // We can then generate a 2D mesh, and save it to disk.
   gmshModelMesh(2);
-
   gmshExport("t1.msh");
 
+  // Gmsh finalize should be called at the end.
   gmshFinalize();
   return 0;
 }
diff --git a/demos/api/t2.cpp b/demos/api/t2.cpp
index 0b2a8e114bcb52b191e6ec11235f0863d2f6754f..9e689f2c7b3a6b5bb8cdf377d861a73ff5665f06 100644
--- a/demos/api/t2.cpp
+++ b/demos/api/t2.cpp
@@ -1,6 +1,7 @@
-#include <gmsh.h>
+// This reimplements gmsh/tutorial/t2.geo in C++. Comments focus on the new API
+// functions used compared to t1.cpp.
 
-// this reimplements gmsh/tutorial/t2.geo
+#include <gmsh.h>
 
 int main(int argc, char **argv)
 {
@@ -9,7 +10,7 @@ int main(int argc, char **argv)
 
   gmshModelCreate("t2");
 
-  // copy/paste from t1.cpp
+  // Copy/paste from t1.cpp
   double lc = 1e-2;
   int o;
   gmshModelGeoAddPoint(1, 0, 0, 0, o, lc);
@@ -28,12 +29,20 @@ int main(int argc, char **argv)
   gmshModelAddPhysicalGroup(1, 2, {1, 2});
   gmshModelAddPhysicalGroup(2, 6, {1});
   gmshModelSetPhysicalName(2, 6, "My surface");
-  // end copy/paste
+  // End copy/paste
 
   gmshModelGeoAddPoint(5, 0, .4, 0, o, lc);
   gmshModelGeoAddLine(5, 4, 5, o);
+
+  // Geometrical transformations take a std::vector of std::pair<int, int> as
+  // first argument, which contains the list of entities, represented by
+  // (dimension,tag) pairs. Here we translate point 3 (dimension = 0, tag = 3),
+  // by dx=-0.05, dy=0, dz=0.
   gmshModelGeoTranslate({{0, 3}}, -0.05, 0, 0);
 
+  // The "Duplicata" functionality in .geo files is handled by
+  // gmshModelGeoCopy(), which takes a vector of (dim,tag) pairs as input, and
+  // returns another vector of (dim,tag) pairs.
   std::vector<std::pair<int, int> > ov, ov2;
   gmshModelGeoCopy({{0, 3}}, ov);
   gmshModelGeoTranslate(ov, 0, 0.1, 0);
@@ -73,11 +82,17 @@ int main(int argc, char **argv)
   gmshModelGeoAddLineLoop(126, {115, 116, 117, 114}, o);
   gmshModelGeoAddPlaneSurface(127, {126}, o);
 
+  // The API to create surface loops ("shells") and volumes is similar to the
+  // one use to create line loops and surfaces.
   gmshModelGeoAddSurfaceLoop(128, {127, 119, 121, 123, 125, 11}, o);
   gmshModelGeoAddVolume(129, {128}, o);
 
+  // Extrusion works as expected, by providing a vector of (dim,tag) pairs as
+  // input, the translation vector, and a vector of (dim,tag) pairs as output.
   gmshModelGeoExtrude({ov[1]}, 0, 0, 0.12, ov2);
 
+  // Mesh sizes associated to geometrical points can be set by passing a vector
+  // of (dim,tag) pairs for the corresponding entities
   gmshModelGeoSetMeshSize({{0,103}, {0,105}, {0,109}, {0,102}, {0,28},
                            {0, 24}, {0,6}, {0,5}}, lc * 3);