Documentation spree no.1

modules/matlab/README

--------------------------------------------------------------------------------
-                          MATLAB WRAPPER GENERATOR
--------------------------------------------------------------------------------
-
-Author:   Hilton Bristow
-Module:   matlab
-Depends:  Matlab, python
-Inputs:   Module headers (<name>/include/opencv2/<name>/<name>.hpp)
-Outputs:  mex libraries wrapping OpenCV functionality
-Date:     2013 Google Summer of Code (GSOC)
-
-This module is designed to automatically generate Matlab mex wrappers for
-other modules within the OpenCV library. Once compiled and added to the Matlab
-path, this gives uses the ability to call OpenCV functions natively from within
-Matlab. Further, it acts as a gateway to writing much more expressive mex
-files, since all the core matrix expressions and arithmetic of OpenCV can 
-be used. 
-
-The generation of Matlab mex wrappers consists of 5 phases. Each phase is 
-explained below, along with information about when the phase is called, the
-relevant files acting in the phase, and the outputs:
-
-1. PARSING EXISTING HEADERS
-------------------
-The main parsing entry point is modules/matlab/generator/gen_matlab_caller.py
-The header parser (modules/python/src2/hdr_parser.py) is invoked on the main
-header on each module to get a list of symbols that are exported into the 
-public API. This is invoked when cmake is parsing the matlab CMakeLists.txt.
-
-
-2. REFACTORING PARSE OUTPUT
-------------------
-The output from the parser is refactored by modules/matlab/generator/parse_tree.py
-into a more functional form. This reconstructs the semantic information of
-the original headers. This is invoked when cmake is parsing the matlab
-CMakeLists.txt.
-
-
-3. POPULATING SOURCE TEMPLATES
-------------------
-Now that we have the exported definitions (namespaces, classes, structs, 
-functions, constants) we synthesise matlab callable wrappers for each using
-a templating system. Jinja does most of the heavy lifting, and we populate
-templates derived from three base templates: template_function_base.cpp,
-template_class_base.cpp and template_doc_base.m found in 
-modules/matlab/generator/templates. During template population we also
-map from OpenCV types to Matlab types and visa versa. This is invoked when
-cmake is parsing the matlab CMakeLists.txt.
-
-
-4. COMPILE SOURCES
-------------------
-We have now done all of the pre-processing work. When make is invoked, we
-compile each of the mex sources (.cpp) down to executables that can be
-called from matlab (.mexmaci64, .mexa64, .mexsol, etc) using the mex 
-compile script that was found when searching for Matlab cmake/OpenCVFindMatlab.cmake.
-
-
-5. INSTALL
-------------------
-When make install is invoked, we install the following:
-  mex:  ${INSTALL_DIR}/lib/matlab/+cv
-  docs: ${INSTALL_DIR}/doc/matlab/cv
-
-The preceding '+' on the lib install path acts as pseudo namespacing within
-Matlab. This makes functions/classes callable with the 'cv.' prefix
-e.g. E = cv.sobel(I); and prevents the global namespace from being trashed