diff --git a/modules/matlab/generator/templates/template_map_base.cpp b/modules/matlab/generator/templates/template_map_base.cpp
index fdbc6c9189..0d39d7165f 100644
--- a/modules/matlab/generator/templates/template_map_base.cpp
+++ b/modules/matlab/generator/templates/template_map_base.cpp
@@ -4,6 +4,22 @@
 
 typedef std::unordered_map Map;
 
+/*! @brief Hash from strings to OpenCV enums
+ *
+ * This is a translation map for strings to OpenCV constants (enums).
+ * When an int is requested from the bridge, and the the mxArray storage 
+ * type is a string, this map is invoked. Thus functions can be called
+ * from Matlab as, e.g.
+ *    cv.dft(x, xf, "DFT_FORWARD");
+ *
+ * Note that an alternative MAtlab class exists as well, so that functions
+ * can be called as, e.g.
+ *    cv.dft(x, xf, cv.DFT_FORWARD);
+ *
+ * This string to int map tends to be faster than its Matlab companion,
+ * but there is no direct access to the value of the constants. It also
+ * enables different error reporting properties.
+ */
 Map<std::string, int> constants = {
   {% for key, val in constants.items() %}
   { "{{key}}", {{val}} },
diff --git a/modules/matlab/generator/templates/template_map_base.m b/modules/matlab/generator/templates/template_map_base.m
index 10dd699f9a..79dee7670c 100644
--- a/modules/matlab/generator/templates/template_map_base.m
+++ b/modules/matlab/generator/templates/template_map_base.m
@@ -1,3 +1,25 @@
+% CV
+% This class enumerates all OpenCV constants, stripping them
+% out of classes where necessary. The constants can then be 
+% used in OpenCV functions by prefixing the class name
+% e.g.
+%   cv.dft(x, xf, cv.DFT_FORWARD);
+%
+% The properties are all declared Constant, so they cannot be
+% changed, however they can be accidentally aliased if you 
+% declare a variable of the same name first. If you're 
+% particularly afraid of aliasing, you can call cv() before
+% calling constants to parse the variable 'cv' as this class
+%
+% Note that calls to this class and calls to methods contained
+% in the namespace cv can happily coexist
+%
+% Users also have the option of calling the constants as strings
+% e.g.
+%   cv.dft(x, xf, "DFT_FORWARD");
+% 
+% This tends to be faster as it is hashed in C++, but the
+% values of the constants cannot be introspected
 classdef cv
     properties (Constant = true)
     {% for key, val in constants.items() %}