├── test ├── .gitignore ├── mtoc.sh.in ├── update_refs.sh ├── test │ └── +grid │ │ └── +rect │ │ ├── @rectgrid │ │ ├── test.m │ │ ├── plot.m │ │ └── rectgrid.m │ │ └── doxygen_in_namespace.m ├── conf ├── test.sh.in ├── conf2 ├── test2_ref.cc ├── test_ref.cc ├── plot2_ref.cc ├── plot_ref.cc ├── doxygen.m ├── classA.m ├── doxygen_in_namespace_ref.cc ├── doxygen_in_namespace2_ref.cc ├── doxygen_ref.cc └── doxygen2_ref.cc ├── src ├── docs │ ├── logo.jpg │ ├── namespaces.c │ ├── footer.html │ ├── tabs.css │ ├── +examples │ │ ├── structArgFunc.m │ │ ├── InheritedClass.m │ │ └── Class.m │ ├── mainpage.c.in │ ├── tipps.c │ ├── faq.c │ ├── troubleshooting.c │ ├── download_licenses.c.in │ ├── changelist.c │ ├── DoxygenLayout.xml │ ├── install.c │ └── tools.c ├── config.h.in ├── mtocpp.cc ├── confscanner.h ├── postprocess.rl └── dirent_msvc.h ├── win32 ├── mtocpp.exe ├── debug │ ├── mtocpp.exe │ ├── mtocpp.ilk │ ├── mtocpp.pdb │ ├── mtocpp_post.exe │ ├── mtocpp_post.ilk │ └── mtocpp_post.pdb └── mtocpp_post.exe ├── win64 ├── mtocpp.exe ├── debug │ ├── mtocpp.exe │ ├── mtocpp.ilk │ ├── mtocpp.pdb │ ├── mtocpp_post.exe │ ├── mtocpp_post.ilk │ └── mtocpp_post.pdb └── mtocpp_post.exe ├── INSTALL ├── ragel-guide-6.6.pdf ├── makepublidocs.sh ├── .gitignore ├── tools └── config │ ├── latexextras.template │ ├── developers.c │ ├── mtocpp.conf │ └── class_substitutes.c ├── cmake ├── WindowsToolChain.cmake └── FindRagel.cmake ├── LICENSE ├── .project ├── README.rst └── CMakeLists.txt /test/.gitignore: -------------------------------------------------------------------------------- 1 | *.cc 2 | !*_ref.cc 3 | .gdbinit 4 | mtoc.sh 5 | -------------------------------------------------------------------------------- /test/mtoc.sh.in: -------------------------------------------------------------------------------- 1 | #!/bin/sh 2 | 3 | @CMAKE_CURRENT_BINARY_DIR@/mtocpp $1 conf 4 | -------------------------------------------------------------------------------- /src/docs/logo.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/src/docs/logo.jpg -------------------------------------------------------------------------------- /win32/mtocpp.exe: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win32/mtocpp.exe -------------------------------------------------------------------------------- /win64/mtocpp.exe: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win64/mtocpp.exe -------------------------------------------------------------------------------- /INSTALL: -------------------------------------------------------------------------------- 1 | Please check http://www.morepas.org/software/mtocpp for installation instructions. -------------------------------------------------------------------------------- /ragel-guide-6.6.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/ragel-guide-6.6.pdf -------------------------------------------------------------------------------- /win32/debug/mtocpp.exe: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win32/debug/mtocpp.exe -------------------------------------------------------------------------------- /win32/debug/mtocpp.ilk: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win32/debug/mtocpp.ilk -------------------------------------------------------------------------------- /win32/debug/mtocpp.pdb: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win32/debug/mtocpp.pdb -------------------------------------------------------------------------------- /win32/mtocpp_post.exe: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win32/mtocpp_post.exe -------------------------------------------------------------------------------- /win64/debug/mtocpp.exe: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win64/debug/mtocpp.exe -------------------------------------------------------------------------------- /win64/debug/mtocpp.ilk: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win64/debug/mtocpp.ilk -------------------------------------------------------------------------------- /win64/debug/mtocpp.pdb: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win64/debug/mtocpp.pdb -------------------------------------------------------------------------------- /win64/mtocpp_post.exe: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win64/mtocpp_post.exe -------------------------------------------------------------------------------- /test/update_refs.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | for i in *_ref.cc; 4 | do 5 | cp ${i/_ref/} $i; 6 | done 7 | -------------------------------------------------------------------------------- /win32/debug/mtocpp_post.exe: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win32/debug/mtocpp_post.exe -------------------------------------------------------------------------------- /win32/debug/mtocpp_post.ilk: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win32/debug/mtocpp_post.ilk -------------------------------------------------------------------------------- /win32/debug/mtocpp_post.pdb: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win32/debug/mtocpp_post.pdb -------------------------------------------------------------------------------- /win64/debug/mtocpp_post.exe: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win64/debug/mtocpp_post.exe -------------------------------------------------------------------------------- /win64/debug/mtocpp_post.ilk: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win64/debug/mtocpp_post.ilk -------------------------------------------------------------------------------- /win64/debug/mtocpp_post.pdb: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mdrohmann/mtocpp/HEAD/win64/debug/mtocpp_post.pdb -------------------------------------------------------------------------------- /makepublidocs.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | DIR=../morepas_web/software/mtocpp/docs 3 | cd build 4 | rm -rf $DIR 5 | cmake -DCMAKE_INSTALL_PREFIX="~/agh" -DCUSTOM_DOC_DIR="$DIR" .. 6 | make install 7 | -------------------------------------------------------------------------------- /test/test/+grid/+rect/@rectgrid/test.m: -------------------------------------------------------------------------------- 1 | function ret = test(auto_param,b,c) 2 | % function ret = test(a,b,c) 3 | % This is a test for a statical method declared outside of the classdef file 4 | % 5 | % Parameters: 6 | % b: second parameter 7 | % c: third parameter of type test 8 | 9 | 10 | end 11 | -------------------------------------------------------------------------------- /src/docs/namespaces.c: -------------------------------------------------------------------------------- 1 | /** @namespace examples 2 | * @brief A namespace/package for example files 3 | * 4 | * @note If you use the 'SHOW_NAMESPACES' option in your 'doxygen' 5 | * configuration file, you need to document @b all your namespaces/packages at 6 | * least with a brief description text. This should be done in a separate file. 7 | * @sa 'namespaces.c' in the 'share/doc/mtoccpp' directory for details. 8 | */ 9 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .gdbinit 2 | .settings 3 | *.o 4 | mtoc 5 | postprocess 6 | accesstest 7 | test/html 8 | src/docs/doxygen.conf 9 | .gdbinit 10 | test/*.cc 11 | CMakeCache.txt 12 | CMakeFiles 13 | *.sw[op] 14 | !test/*_ref.cc 15 | docs/ 16 | !src/docs 17 | build/ 18 | build64/ 19 | *.*~ 20 | *.diff 21 | *.zip 22 | *.tar.gz 23 | published/ 24 | website 25 | problems/ 26 | Debug/ 27 | morepas_web 28 | old_versions 29 | make*.sh 30 | src/docs/download_licenses.c 31 | src/docs/mainpage.c 32 | -------------------------------------------------------------------------------- /test/test/+grid/+rect/@rectgrid/plot.m: -------------------------------------------------------------------------------- 1 | function p = plot(grid,params) 2 | %function p = plot(grid [,params]) 3 | % plot function 4 | % 5 | % Parameters: 6 | % params: object of type plot_params 7 | % 8 | % plot of a rectgrid via plot_polygon_grid 9 | % see help plot_polygon_grid for further information 10 | 11 | % Bernard Haasdonk 9.5.2007 12 | 13 | if (nargin <2) 14 | params = []; 15 | end; 16 | 17 | % simply forward the call 18 | p = plot_polygon_grid(grid,params); 19 | % TO BE ADJUSTED TO NEW SYNTAX 20 | %| \docupdate 21 | -------------------------------------------------------------------------------- /tools/config/latexextras.template: -------------------------------------------------------------------------------- 1 | % Additional LaTeX inclusions for mtoc++/doxygen tools 2 | % 3 | % Use the _ConfDir_ tag to insert the folder where this file resides. 4 | % Thus you can include more custom latex files/styles/packages which reside in this folder 5 | 6 | % Default packages 7 | \usepackage{amsmath} 8 | \usepackage{amssymb} 9 | %\usepackage{amsfonts} 10 | %\usepackage{subfig} 11 | %\usepackage{bbm} 12 | 13 | % Inclusion example: 14 | % Please note that, independent of windows or unix, latex uses forward-slash-type paths in bibliography. 15 | %\input{_ConfDirFwdSlash_/myexternalstyle.sty} -------------------------------------------------------------------------------- /cmake/WindowsToolChain.cmake: -------------------------------------------------------------------------------- 1 | # the name of the target operating system 2 | SET(CMAKE_SYSTEM_NAME Windows) 3 | 4 | # which compilers to use for C and C++ 5 | SET(CMAKE_C_COMPILER i586-mingw32msvc-gcc) 6 | SET(CMAKE_CXX_COMPILER i586-mingw32msvc-g++) 7 | SET(CMAKE_RC_COMPILER i586-mingw32msvc-windres) 8 | 9 | # here is the target environment located 10 | SET(CMAKE_FIND_ROOT_PATH /usr/i586msvc-mingw32) 11 | 12 | # adjust the default behaviour of the FIND_XXX() commands: 13 | # search headers and libraries in the target environment, search 14 | # programs in the host environment 15 | set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) 16 | set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) 17 | set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) 18 | -------------------------------------------------------------------------------- /src/docs/footer.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 12 | 13 | 14 |
15 | $projectname $projectnumber docs generated by 16 | doxygen 17 | $doxygenversion 18 |
19 | 20 | 21 | 22 | -------------------------------------------------------------------------------- /src/docs/tabs.css: -------------------------------------------------------------------------------- 1 | .tabs, .tabs2, .tabs3 { 2 | background-color: #8BB9E0; 3 | border-bottom: 1px solid #268BE0; 4 | width: 100%; 5 | z-index: 101; 6 | font-size: 13px; 7 | } 8 | 9 | .tabs2 { 10 | font-size: 10px; 11 | } 12 | .tabs3 { 13 | font-size: 9px; 14 | } 15 | 16 | .tablist { 17 | margin: 0; 18 | padding: 0; 19 | display: table; 20 | } 21 | 22 | .tablist li { 23 | float: left; 24 | display: table-cell; 25 | line-height: 36px; 26 | list-style: none; 27 | } 28 | 29 | .tablist a { 30 | display: block; 31 | padding: 0 20px; 32 | font-weight: bold; 33 | color: #283A5D; 34 | text-decoration: none; 35 | outline: none; 36 | } 37 | 38 | .tabs3 .tablist a { 39 | padding: 0 10px; 40 | } 41 | 42 | .tablist a:hover { 43 | color: #fff; 44 | text-decoration: none; 45 | } 46 | 47 | .tablist li.current a { 48 | color: #fff; 49 | } 50 | -------------------------------------------------------------------------------- /test/conf: -------------------------------------------------------------------------------- 1 | # Configurations 2 | 3 | LATEX_OUTPUT := false; 4 | 5 | # PRINT_FIELDS := false; 6 | 7 | AUTO_ADD_FIELDS := true; 8 | 9 | AUTO_ADD_PARAMETERS := true; 10 | 11 | AUTO_ADD_CLASS_PROPERTIES := true; 12 | 13 | AUTO_ADD_CLASS := true; 14 | 15 | REMOVE_FIRST_ARG_IN_ABSTRACT_METHODS := true; 16 | 17 | ENABLE_OF_TYPE_PARSING := true; 18 | 19 | ## 20 | 21 | add(params) = auto_param => """ object of type gridbase.gridbase which is not used! This documentation is added automatically! """; 22 | 23 | add(fields) = auto_struct.auto_field => """ This field's documentation has been added automatically! """; 24 | 25 | glob = * { groups = test; } 26 | 27 | glob = test { 28 | add(params) = auto_param => """ object of type othergrid which is not used! This documentation is added automatically! """; 29 | } 30 | 31 | glob = doxygen.m { add(params) = auto_param => """ jajaja """; } 32 | 33 | # vim: set ft=perl et sw=2 : 34 | -------------------------------------------------------------------------------- /test/test.sh.in: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | function doit() { 4 | SUFFIX=$1; 5 | for MFILE in $FILES 6 | do 7 | echo "Checking $MFILE ..." 8 | MBFILE=`basename $MFILE` 9 | CCFILE="${MBFILE%.m}${SUFFIX}.cc" 10 | CCREFFILE="${MBFILE%.m}${SUFFIX}_ref.cc" 11 | DIFFFILE="${MBFILE%.m}${SUFFIX}.diff" 12 | $MTOCPP $MFILE conf$SUFFIX > $CCFILE 13 | if diff --strip-trailing-cr -u $CCFILE $CCREFFILE > $DIFFFILE 14 | then 15 | echo " (passed)" 16 | rm $DIFFFILE 17 | else 18 | echo " (failed)" 19 | fi 20 | done 21 | } 22 | 23 | FILES="test/+grid/+rect/@rectgrid/*.m test/+grid/+rect/doxygen_in_namespace.m ./*.m" 24 | 25 | cd @CMAKE_CURRENT_SOURCE_DIR@/test 26 | 27 | if [ -x @CMAKE_CURRENT_BINARY_DIR@/mtocpp ]; 28 | then 29 | MTOCPP=@CMAKE_CURRENT_BINARY_DIR@/mtocpp 30 | else 31 | MTOCPP="wine @CMAKE_CURRENT_BINARY_DIR@/mtocpp.exe" 32 | fi 33 | 34 | doit "" 35 | doit "2" 36 | -------------------------------------------------------------------------------- /src/config.h.in: -------------------------------------------------------------------------------- 1 | // the configured options and settings for Tutorial 2 | #define MTOCPP_VERSION_MAJOR @MTOC++_VERSION_MAJOR@ 3 | #define MTOCPP_VERSION_MINOR @MTOC++_VERSION_MINOR@ 4 | 5 | // defaults for config files 6 | #define PRINT_FIELDS true 7 | #define AUTO_ADD_FIELDS false 8 | #define AUTO_ADD_PARAMETERS false 9 | #define AUTO_ADD_CLASS_PROPERTIES false 10 | #define AUTO_ADD_CLASSES true 11 | #define COPY_TYPIFIED_FIELD_DOCU false 12 | #define REMOVE_FIRST_ARG_IN_ABSTRACT_METHODS true 13 | #define ENABLE_OF_TYPE_PARSING true 14 | #define VOID_TYPE_IN_RETURN_VALUES false 15 | #define PRINT_RETURN_VALUE_NAME 2 16 | #define GENERATE_SUBFUNTION_DOCUMENTATION false 17 | 18 | // Damn arbitrary flag naming.. 19 | #if defined(_WIN32) || defined (_WIN64) // MS VS 2010 (any hopefully others) define _WINXX on windows platforms 20 | #define WIN32 1 21 | #endif 22 | -------------------------------------------------------------------------------- /test/conf2: -------------------------------------------------------------------------------- 1 | # Configurations 2 | 3 | LATEX_OUTPUT := false; 4 | 5 | # PRINT_FIELDS := false; 6 | 7 | AUTO_ADD_FIELDS := false; 8 | 9 | AUTO_ADD_PARAMETERS := false; 10 | 11 | AUTO_ADD_CLASS_PROPERTIES := false; 12 | 13 | AUTO_ADD_CLASS := false; 14 | 15 | REMOVE_FIRST_ARG_IN_ABSTRACT_METHODS := true; 16 | 17 | ENABLE_OF_TYPE_PARSING := true; 18 | 19 | VOID_TYPE_IN_RETURN_VALUES := true; 20 | 21 | PRINT_RETURN_VALUE_NAME := 1; 22 | 23 | GENERATE_SUBFUNTION_DOCUMENTATION := true; 24 | 25 | ## 26 | 27 | add(params) = auto_param => """ object of type gridbase.gridbase which is not used! This documentation is added automatically! """; 28 | 29 | add(fields) = auto_struct.auto_field => """ This field's documentation has been added automatically! """; 30 | 31 | glob = * { groups = test; } 32 | 33 | glob = test { 34 | add(params) = auto_param => """ object of type othergrid which is not used! This documentation is added automatically! """; 35 | } 36 | 37 | glob = doxygen.m { add(params) = auto_param => """ jajaja """; } 38 | 39 | # vim: set ft=perl et sw=2 : 40 | -------------------------------------------------------------------------------- /tools/config/developers.c: -------------------------------------------------------------------------------- 1 | /* 2 | * This file is included in order to give correct links to the developers of mtoc++ for the MatLabDocMaker, 3 | * if included in the documentation. 4 | * 5 | * If you are also making use of the @change/@new tags you will also have a similar project-specific development page. 6 | * However, then you might want to add an ingroup-doxygen tag here in order to neatly include this generated page at an appropriate place. 7 | * Unfortunately, the versions used in the MatLabDocMaker.m file naturally correspond to the 8 | * internal mtoc++-versions and will of course differ from those used in your project. If this bothers you all too much, feel free to 9 | * remove the corresponding tags from the MatlabDocMaker file, as probably wont come up with a hack for this too soon :-) 10 | */ 11 | /** 12 | * @page developers mtoc++ Developers 13 | * @section md Martin Drohmann 14 | * http://wwwmath.uni-muenster.de/u/martin.drohmann 15 | * 16 | *- Lead Programmer 17 | *- Ragel expert :-) 18 | * 19 | * @section dw Daniel Wirtz 20 | * http://www.agh.ians.uni-stuttgart.de/orga/people/wirtz 21 | * 22 | *- Programming 23 | *- Maintenance Matlab File Exchange 24 | *- Windows binaries (VS2010) 25 | */ 26 | -------------------------------------------------------------------------------- /src/docs/+examples/structArgFunc.m: -------------------------------------------------------------------------------- 1 | function rv = structArgFunc(struct1, struct2) 2 | % A function with struct arguments 3 | % 4 | % When working with structs you can also specify the required and optional 5 | % fields. This feature is deprecated. It can be activated setting the flag 6 | % 'AUTO_ADD_FIELDS' to 'true' in the mtoc++ configuration file. 7 | % 8 | % A line beginning with the words "Required fields of", "optional fields of" or 9 | % "generated fields of" start a block for descriptions for fields used by the 10 | % parameters or generated for the return values. 11 | % 12 | % Required fields of struct1: 13 | % test: Description for required field struct1.test 14 | % 15 | % Optional fields of struct2: 16 | % test2: Description for optional field struct2.test2 17 | % 18 | % Generated fields of rv: 19 | % RB: Description for generated field rv.RB 20 | % 21 | % fields of parameters that are used in the function body are added to the 22 | % required fileds list automatically, if they are not documentated yet. 23 | struct1.auto_added; 24 | 25 | struct2.auto_added; 26 | 27 | % fields of return values that are assigned somewhere in the function body are 28 | % also added automatically to the list of generated fields 29 | rv.auto_added = 1; 30 | 31 | function dummy = subFunction(a, b) 32 | % documentation of a subfunction 33 | 34 | nope; 35 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2015, Martin Drohmann, Daniel Wirtz 2 | All rights reserved. 3 | 4 | Redistribution and use in source and binary forms, with or without 5 | modification, are permitted provided that the following conditions are 6 | met: 7 | 8 | * Redistributions of source code must retain the above copyright 9 | notice, this list of conditions and the following disclaimer. 10 | * Redistributions in binary form must reproduce the above copyright 11 | notice, this list of conditions and the following disclaimer in 12 | the documentation and/or other materials provided with the distribution 13 | 14 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 15 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17 | ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 18 | LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 19 | CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 20 | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 21 | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 22 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 23 | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 24 | POSSIBILITY OF SUCH DAMAGE. 25 | -------------------------------------------------------------------------------- /test/test2_ref.cc: -------------------------------------------------------------------------------- 1 | #include "rectgrid.m" 2 | namespace grid{ 3 | namespace rect{ 4 | 5 | 6 | /* (Autoinserted by mtoc++) 7 | * This source code has been filtered by the mtoc++ executable, 8 | * which generates code that can be processed by the doxygen documentation tool. 9 | * 10 | * On the other hand, it can neither be interpreted by MATLAB, nor can it be compiled with a C++ compiler. 11 | * Except for the comments, the function bodies of your M-file functions are untouched. 12 | * Consequently, the FILTER_SOURCE_FILES doxygen switch (default in our Doxyfile.template) will produce 13 | * attached source files that are highly readable by humans. 14 | * 15 | * Additionally, links in the doxygen generated documentation to the source code of functions and class members refer to 16 | * the correct locations in the source code browser. 17 | * However, the line numbers most likely do not correspond to the line numbers in the original MATLAB source files. 18 | */ 19 | 20 | static mlhsInnerSubst grid::rect::rectgrid::test(::othergrid auto_param,matlabtypesubstitute b,::test c) { 21 | 22 | 23 | 24 | end 25 | 26 | } 27 | /** @fn mlhsInnerSubst grid::rect::rectgrid::test(::othergrid auto_param,matlabtypesubstitute b,::test c) 28 | * @brief This is a test for a statical method declared outside of the classdef file 29 | * 30 | * 31 | * @param auto_param object which is not used! This documentation is added automatically! 32 | * @param b second parameter 33 | * @param c third parameter 34 | * 35 | */ 36 | 37 | }; 38 | }; 39 | -------------------------------------------------------------------------------- /test/test_ref.cc: -------------------------------------------------------------------------------- 1 | #include "rectgrid.m" 2 | namespace grid{ 3 | namespace rect{ 4 | 5 | 6 | /* (Autoinserted by mtoc++) 7 | * This source code has been filtered by the mtoc++ executable, 8 | * which generates code that can be processed by the doxygen documentation tool. 9 | * 10 | * On the other hand, it can neither be interpreted by MATLAB, nor can it be compiled with a C++ compiler. 11 | * Except for the comments, the function bodies of your M-file functions are untouched. 12 | * Consequently, the FILTER_SOURCE_FILES doxygen switch (default in our Doxyfile.template) will produce 13 | * attached source files that are highly readable by humans. 14 | * 15 | * Additionally, links in the doxygen generated documentation to the source code of functions and class members refer to 16 | * the correct locations in the source code browser. 17 | * However, the line numbers most likely do not correspond to the line numbers in the original MATLAB source files. 18 | */ 19 | 20 | static mlhsInnerSubst grid::rect::rectgrid::test(::othergrid auto_param,matlabtypesubstitute b,::test c) { 21 | 22 | 23 | 24 | end 25 | 26 | } 27 | /** @fn mlhsInnerSubst grid::rect::rectgrid::test(::othergrid auto_param,matlabtypesubstitute b,::test c) 28 | * @brief This is a test for a statical method declared outside of the classdef file 29 | * 30 | * 31 | * @param auto_param object which is not used! This documentation is added automatically! 32 | * @param b second parameter 33 | * @param c third parameter 34 | * 35 | * @retval ret ret 36 | */ 37 | 38 | }; 39 | }; 40 | -------------------------------------------------------------------------------- /test/plot2_ref.cc: -------------------------------------------------------------------------------- 1 | #include "rectgrid.m" 2 | namespace grid{ 3 | namespace rect{ 4 | 5 | 6 | /* (Autoinserted by mtoc++) 7 | * This source code has been filtered by the mtoc++ executable, 8 | * which generates code that can be processed by the doxygen documentation tool. 9 | * 10 | * On the other hand, it can neither be interpreted by MATLAB, nor can it be compiled with a C++ compiler. 11 | * Except for the comments, the function bodies of your M-file functions are untouched. 12 | * Consequently, the FILTER_SOURCE_FILES doxygen switch (default in our Doxyfile.template) will produce 13 | * attached source files that are highly readable by humans. 14 | * 15 | * Additionally, links in the doxygen generated documentation to the source code of functions and class members refer to 16 | * the correct locations in the source code browser. 17 | * However, the line numbers most likely do not correspond to the line numbers in the original MATLAB source files. 18 | */ 19 | 20 | mlhsInnerSubst grid::rect::rectgrid::plot(::plot_params params) { 21 | 22 | 23 | /* Bernard Haasdonk 9.5.2007 */ 24 | 25 | if (nargin <2) 26 | params = []; 27 | end; 28 | 29 | /* simply forward the call */ 30 | p = plot_polygon_grid(grid,params); 31 | /* */ 32 | /** \docupdate */ 33 | 34 | } 35 | /** @fn mlhsInnerSubst grid::rect::rectgrid::plot(::plot_params params) 36 | * @brief plot function 37 | * 38 | * 39 | * plot of a rectgrid via plot_polygon_grid 40 | * see help plot_polygon_grid for further information 41 | * 42 | * @param params object 43 | * 44 | * @synupdate Syntax needs to be updated! 45 | */ 46 | 47 | }; 48 | }; 49 | -------------------------------------------------------------------------------- /cmake/FindRagel.cmake: -------------------------------------------------------------------------------- 1 | # This file is copied from the fcgi-debug available at 2 | # http://cgit.stbuehler.de/gitosis/fcgi-debug 3 | 4 | IF(NOT RAGEL_EXECUTABLE) 5 | MESSAGE(STATUS "Looking for ragel") 6 | FIND_PROGRAM(RAGEL_EXECUTABLE ragel) 7 | IF(RAGEL_EXECUTABLE) 8 | EXECUTE_PROCESS(COMMAND "${RAGEL_EXECUTABLE}" -v OUTPUT_VARIABLE _version) 9 | STRING(REGEX MATCH "[0-9.]+" RAGEL_VERSION ${_version}) 10 | SET(RAGEL_FOUND TRUE) 11 | ENDIF(RAGEL_EXECUTABLE) 12 | ELSE(NOT RAGEL_EXECUTABLE) 13 | EXECUTE_PROCESS(COMMAND "${RAGEL_EXECUTABLE}" -v OUTPUT_VARIABLE _version) 14 | STRING(REGEX MATCH "[0-9.]+" RAGEL_VERSION ${_version}) 15 | SET(RAGEL_FOUND TRUE) 16 | ENDIF(NOT RAGEL_EXECUTABLE) 17 | 18 | IF(RAGEL_FOUND) 19 | IF (NOT Ragel_FIND_QUIETLY) 20 | MESSAGE(STATUS "Found ragel: ${RAGEL_EXECUTABLE} (${RAGEL_VERSION})") 21 | ENDIF (NOT Ragel_FIND_QUIETLY) 22 | 23 | IF(NOT RAGEL_FLAGS) 24 | SET(RAGEL_FLAGS "-T0") 25 | ENDIF(NOT RAGEL_FLAGS) 26 | 27 | MACRO(RAGEL_PARSER SRCFILE) 28 | GET_FILENAME_COMPONENT(SRCBASE "${SRCFILE}" NAME_WE) 29 | SET(OUTFILE "${CMAKE_CURRENT_BINARY_DIR}/${SRCBASE}.cc") 30 | SET(INFILE "${CMAKE_CURRENT_SOURCE_DIR}/${SRCFILE}.rl") 31 | ADD_CUSTOM_COMMAND(OUTPUT ${OUTFILE} 32 | COMMAND "${RAGEL_EXECUTABLE}" 33 | ARGS -C ${RAGEL_FLAGS} -o "${OUTFILE}" "${INFILE}" 34 | DEPENDS "${INFILE}" 35 | COMMENT "Generating ${SRCBASE}.cc from ${SRCFILE}.rl" 36 | ) 37 | ENDMACRO(RAGEL_PARSER) 38 | 39 | ELSE(RAGEL_FOUND) 40 | 41 | IF(Ragel_FIND_REQUIRED) 42 | MESSAGE(FATAL_ERROR "Could not find ragel") 43 | ENDIF(Ragel_FIND_REQUIRED) 44 | ENDIF(RAGEL_FOUND) 45 | -------------------------------------------------------------------------------- /src/docs/mainpage.c.in: -------------------------------------------------------------------------------- 1 | /** 2 | * @mainpage mtoc++ ${MTOC++_VERSION} Software Documentation 3 | * @section intro Introduction 4 | * 5 | * The mtoc++ software comprises two programs to build nice Doxygen documentation for Matlab projects. 6 | * 7 | * The filter program 'mtocpp' transforms relevant parts of the M-Files into C++ syntax, which can be parsed by doxygen. 8 | * The generated html files can be processed by the program 'mtocpp_post' in order to generate documentation looking more like Matlab. 9 | * 10 | * Short mtoc++ feature list: 11 | * - Transforms function m-files into standalone functions 12 | * - Supports most of the OOP features from Matlab. 13 | * 14 | * See the @ref examples.Class class for detailed examples on how to use mtoc++ with Matlab. 15 | * The documentation has been created using mtoc++. 16 | * 17 | * @section Contents 18 | * - @subpage download 19 | * - @subpage install 20 | * - @subpage tools 21 | * - @subpage tips 22 | * - @subpage changes 23 | * - @subpage licensing 24 | * - @subpage troubleshooting 25 | * 26 | * @section Downloads 27 | * For all available downloads check @ref download. The most current (official) release can be downloaded below. 28 | * 29 | * @par Documentation 30 | * This documentation can also be downloaded as (doxygen/mtoc++ generated) PDF. 31 | * 32 | * @par Release ${MTOC++_VERSION} (${CURRENT_DATE}) 33 | * - GitHub 34 | * - Source tarball 35 | * - Windows binaries and tools 36 | * 37 | */ 38 | -------------------------------------------------------------------------------- /test/plot_ref.cc: -------------------------------------------------------------------------------- 1 | #include "rectgrid.m" 2 | namespace grid{ 3 | namespace rect{ 4 | 5 | 6 | /* (Autoinserted by mtoc++) 7 | * This source code has been filtered by the mtoc++ executable, 8 | * which generates code that can be processed by the doxygen documentation tool. 9 | * 10 | * On the other hand, it can neither be interpreted by MATLAB, nor can it be compiled with a C++ compiler. 11 | * Except for the comments, the function bodies of your M-file functions are untouched. 12 | * Consequently, the FILTER_SOURCE_FILES doxygen switch (default in our Doxyfile.template) will produce 13 | * attached source files that are highly readable by humans. 14 | * 15 | * Additionally, links in the doxygen generated documentation to the source code of functions and class members refer to 16 | * the correct locations in the source code browser. 17 | * However, the line numbers most likely do not correspond to the line numbers in the original MATLAB source files. 18 | */ 19 | 20 | mlhsInnerSubst grid::rect::rectgrid::plot(::plot_params params) { 21 | 22 | 23 | /* Bernard Haasdonk 9.5.2007 */ 24 | 25 | if (nargin <2) 26 | params = []; 27 | end; 28 | 29 | /* simply forward the call */ 30 | p = plot_polygon_grid(grid,params); 31 | /* */ 32 | /** \docupdate */ 33 | 34 | } 35 | /** @fn mlhsInnerSubst grid::rect::rectgrid::plot(::plot_params params) 36 | * @brief plot function 37 | * 38 | * 39 | * plot of a rectgrid via plot_polygon_grid 40 | * see help plot_polygon_grid for further information 41 | * 42 | * @param params object 43 | * 44 | * @retval p p 45 | * @synupdate Syntax needs to be updated! 46 | */ 47 | 48 | }; 49 | }; 50 | -------------------------------------------------------------------------------- /src/docs/tipps.c: -------------------------------------------------------------------------------- 1 | /** @page tips Tips for doxygen usage with mtoc 2 | * 3 | * @section tip_versioning Feature and change tracking information 4 | * 5 | * @subsection dg_featchange New feature and change log commands 6 | * New features can be tracked version-based via using 7 | * @verbatim 8 | * @new{, , [, ]} 9 | * @endverbatim 10 | * 11 | * For example, writing 12 | * @verbatim 13 | * @new{0,1,dw} Added a fancy new feature! (New feature Example) 14 | * @endverbatim 15 | * results in 16 | * @new{0,1,dw} Added a fancy new feature! (New feature Example) 17 | * 18 | * To include a date write 19 | * @verbatim 20 | * @new{0,1,dw,2011-01-01} Added a fancy new feature on new year's! (New feature Example) 21 | * @endverbatim 22 | * results in 23 | * @new{0,1,dw,2011-01-01} Added a fancy new feature on new year's! (New feature Example) 24 | * 25 | * and a new related page called @ref newfeat01 listing these 26 | * items. To refer to that Changelog page, use the keyword 'newfeat' 27 | * together with both plainly concatenated numbers: 28 | * @verbatim 29 | * @ref newfeat01 30 | * @endverbatim 31 | * gives @ref newfeat01 32 | * 33 | * Changes can be tracked version-based via using 34 | * @verbatim 35 | * @change{, , [, ]} 36 | * @endverbatim 37 | * 38 | * For example, writing 39 | * @verbatim 40 | * @change{0,1,dw} Changed foo to bar! (Changelog Example) 41 | * @endverbatim 42 | * results in 43 | * @change{0,1,dw} Changed foo to bar! (Changelog Example) 44 | * 45 | * The optional date works same as with the '@@new' command. The 46 | * related page keys for changes are composed by the keyword 'changelog' 47 | * and both plainly concatenated numbers (similar to the new feature 48 | * keys). 49 | * 50 | * 51 | */ 52 | -------------------------------------------------------------------------------- /src/docs/faq.c: -------------------------------------------------------------------------------- 1 | /** 2 | * @page faq mtoc++ FAQ 3 | * 4 | * @section faq_general General issues with mtoc++ 5 | * 6 | * @par How do I generate LaTeX output? 7 | * LaTeX is supported by doxygen and partly by mtoc++. Partly to that extend that, the mtocpp_post postprocessor 8 | * is designed to correct the format of the produced HTML, but not the LaTeX output (very different!). 9 | * It is run nontheless, but will not produce such a nice output as HTML pages. 10 | * However, use the MatlabDocMaker with the option ('latex',true) to generate LaTeX output. 11 | * If you configure Doxygen yourself (see @ref tools_direct) with LaTeX output, latex will complain about the missing "latexextras.sty", which are 12 | * temporarily created by the DocMaker at creation time. Remove the inclusion (or setup your own latex inclusion file) to get that right. 13 | * 14 | * @par Can mtoc++ handle varargin arguments with inputParser? (2013-07-18, Thanks to Alexander Pfeiffer, EADS) 15 | * Yes, mtoc++ can understand the inputParser syntax and will generally create an extra "parameter description" part to the parameter 16 | * list. If you want to add specific information or a comment in general about the extra arguments, you can use 17 | * the syntax @code varargin: @endcode to make mtoc++ add a comment to the optional argument list. 18 | * See the examples.Class class for a demo function. 19 | * 20 | * @par Where should i put the configuration files and output directory? 21 | * Even though it is no requirement regarding mtoc++, it is good style/project management if you have a root folder 22 | * containing all project-related things in a flat hierarchy, meaning you have a "src" folder with sources and a separate 23 | * one "docs" containing the documentation. however, the configuration files (tools/config) should be copied 24 | * into the source folder (e.g. "src/docs_config") for each project to keep things together and versioned, if e.g. GIT or SVN is used. 25 | * 26 | * @section faq_unix UNIX-related questions 27 | * 28 | * @section faq_windows Windows-related questions 29 | * 30 | * @section todo_collection ToDo-Collection 31 | * @todo disable mtoc++ processing in @verbatim environments (at least via switch in mtocpp.conf) 32 | * @todo finish enum support (simple list is working, but mtocpp breaks if comments are present) 33 | * 34 | */ 35 | -------------------------------------------------------------------------------- /src/docs/troubleshooting.c: -------------------------------------------------------------------------------- 1 | /** 2 | * @page troubleshooting Troubleshooting mtoc++ 3 | * @short Some hopefully useful hints when things dont go as they should! 4 | * 5 | * @section ts_config Configuration 6 | * @attention The first and most important message: KNOWLEDGE OF DOXYGEN IS ESSENTIAL! 7 | * 8 | * mtoc++ is designed as a filter for MatLab m-files, so that they can be processed by doxygen as if they were C source files. 9 | * Everything else regarding tags, conventions and possible formatting of display is completely defined by Doxygen. 10 | * So, unless explicitly explained as "feature" of mtoc++ here, one should look into Doxygen's documentation pages 11 | * first before complaining about some stuff that mtoc++ surprisingly cannot do. 12 | * 13 | * Check out the @ref tools_direct section for details on how mtoc++ works. 14 | * 15 | * @section ts_path Issues finding binaries (MAC) 16 | * Thanks to a report from K. Kearney to resolve path issues on MAC platforms: 17 | * 18 | * "After building, I added \c /mtoc++_1.4/tools to my Matlab path and tried to run MacDocMaker.setup. I encountered an issue where Matlab couldn't locate either mtocpp or latex. I think this is a Mac-specific issue; when you start Matlab in the standard way, from the Dock (rather than through the command-line matlab command), the shell it starts doesn't run any configuration scripts (.bashrc, .back_profile, etc) or set system paths. I think some versions of Matlab have a .matlabrc.sh file that can be modified to set a PATH, and I've seen something on the newsgroup about .plist files, but I just force the Matlab shell it to match my other Terminal sessions by adding the following lines to the top of the matlab shell script (/bin/matlab): 19 | * @code 20 | * source ~/.bash_profile 21 | * source /etc/bashrc 22 | * source /etc/profile@endcode 23 | * 24 | * With that change (and after restarting Matlab), I was able to successfully run MatlabDocMaker.setup, and then MatlabDocMaker.create on a test directory." 25 | * 26 | * @section ts_debug Debugging mtoc++ 27 | * For hard cases like segfaults there is also hope! 28 | * 29 | * You can build your mtoc++ binaries with the \c Debug build type (starting in the source folder): 30 | * @code 31 | * mkdir build 32 | * cd build 33 | * cmake -DCMAKE_BUILD_TYPE=Debug .. 34 | * make 35 | * @endcode 36 | * Then, send the compiled binaries along with the used source code to us and we will try to figure out what the heck is wrong with it! 37 | */ -------------------------------------------------------------------------------- /.project: -------------------------------------------------------------------------------- 1 | 2 | 3 | mtoc++ 4 | 5 | 6 | 7 | 8 | 9 | org.eclipse.cdt.managedbuilder.core.genmakebuilder 10 | clean,full,incremental, 11 | 12 | 13 | ?name? 14 | 15 | 16 | 17 | org.eclipse.cdt.make.core.append_environment 18 | true 19 | 20 | 21 | org.eclipse.cdt.make.core.autoBuildTarget 22 | all 23 | 24 | 25 | org.eclipse.cdt.make.core.buildArguments 26 | 27 | 28 | 29 | org.eclipse.cdt.make.core.buildCommand 30 | make 31 | 32 | 33 | org.eclipse.cdt.make.core.buildLocation 34 | ${workspace_loc:/mtoc++/Debug} 35 | 36 | 37 | org.eclipse.cdt.make.core.cleanBuildTarget 38 | clean 39 | 40 | 41 | org.eclipse.cdt.make.core.contents 42 | org.eclipse.cdt.make.core.activeConfigSettings 43 | 44 | 45 | org.eclipse.cdt.make.core.enableAutoBuild 46 | false 47 | 48 | 49 | org.eclipse.cdt.make.core.enableCleanBuild 50 | true 51 | 52 | 53 | org.eclipse.cdt.make.core.enableFullBuild 54 | true 55 | 56 | 57 | org.eclipse.cdt.make.core.fullBuildTarget 58 | all 59 | 60 | 61 | org.eclipse.cdt.make.core.stopOnError 62 | true 63 | 64 | 65 | org.eclipse.cdt.make.core.useDefaultBuildCmd 66 | true 67 | 68 | 69 | 70 | 71 | org.eclipse.cdt.managedbuilder.core.ScannerConfigBuilder 72 | full,incremental, 73 | 74 | 75 | 76 | 77 | 78 | org.eclipse.cdt.core.cnature 79 | org.eclipse.cdt.core.ccnature 80 | org.eclipse.cdt.managedbuilder.core.managedBuildNature 81 | org.eclipse.cdt.managedbuilder.core.ScannerConfigNature 82 | 83 | 84 | -------------------------------------------------------------------------------- /src/docs/download_licenses.c.in: -------------------------------------------------------------------------------- 1 | /** 2 | * @page download Downloading mtoc++ ${MTOC++_VERSION} 3 | * @short mtoc++ download sources and variants 4 | * 5 | * The sources for mtoc++ are accessible as 6 | * - Source tarball 7 | * - Windows binaries 8 | * - Via the GIT versioning system 9 | * 10 | * Once you've obtained your copy check out the @ref install 11 | * 12 | * @note For Windows binaries from this page you might need to install the 13 | * Microsoft Visual C++ 2012 redistributables. 14 | * 15 | * @section git Obtaining mtoc++ via the GIT versioning system 16 | * In order to always stay up-to-date with the latest (development) mtoc++ versions, simply pull it from our GIT repository and 17 | * recompile it when a new release is available. For more information about GIT checkout their website 18 | * 19 | * The GIT repository can currently be found at https://github.com/mdrohmann and a direct clone is possible via 20 | * @code git clone https://github.com/mdrohmann/mtocpp.git mtocpp @endcode 21 | * 22 | * @section mtocrelease mtoc++ ${MTOC++_VERSION} 23 | * - This documentation as PDF. 24 | * - Source tarball 25 | * - Windows binaries (32/64bit) and tools 26 | * - Windows binaries (32/64bit) 27 | * 28 | * @page licensing mtoc++ license conditions 29 | * @short This software is available under the BSD license http://www.opensource.org/licenses/bsd-license.php 30 | * 31 | * Copyright (c) 2010-2015, Martin Drohmann, Daniel Wirtz 32 | * All rights reserved. 33 | * 34 | * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 35 | * - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 36 | * - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 37 | * 38 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 39 | * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR 40 | * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 41 | * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 42 | * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 43 | * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 44 | */ 45 | -------------------------------------------------------------------------------- /src/mtocpp.cc: -------------------------------------------------------------------------------- 1 | #include "mfilescanner.h" 2 | 3 | #include 4 | #include 5 | #include 6 | #include 7 | #include 8 | #include 9 | #ifdef WIN32 10 | #define PATH_MAX 4096 11 | #else 12 | #ifdef __APPLE__ 13 | #include 14 | #else 15 | #include 16 | #endif 17 | #endif 18 | 19 | using std::cerr; 20 | using std::cout; 21 | using std::cin; 22 | using std::endl; 23 | using std::string; 24 | using std::vector; 25 | using std::list; 26 | using std::copy; 27 | using std::map; 28 | using std::set; 29 | using std::istream; 30 | using std::ifstream; 31 | using std::ostream; 32 | using std::ostream_iterator; 33 | using std::ostringstream; 34 | 35 | void usage() 36 | { 37 | cout 38 | << "This is mtocpp Version " << MTOCPP_VERSION_MAJOR << "." << MTOCPP_VERSION_MINOR << "\n" 39 | << "\n" 40 | << "mtocpp parses the Matlab m-file and produces c++-compliant output that can be processed by doxygen.\n" 41 | << "\n" 42 | << "Usage: mtocpp []\n" 43 | << " mtocpp --help\n" 44 | << "\n" 45 | << "If no explicit configuration file is given, mtocpp also looks for './mtocpp.conf' by default." << endl; 46 | } 47 | 48 | // main routine 49 | int main(int argc, char ** argv) 50 | { 51 | istream * fcin; 52 | std::ifstream fin; 53 | string filename; 54 | if(argc >= 2) 55 | { 56 | if (string(argv[1]) == string("--help")) 57 | { 58 | usage(); 59 | exit(0); 60 | } 61 | if (string(argv[1]) == string("--version")) 62 | { 63 | cout << MTOCPP_VERSION_MAJOR << "." << MTOCPP_VERSION_MINOR << endl; 64 | exit(0); 65 | } 66 | std::ios_base::iostate oldstate = fin.exceptions(); 67 | fin.exceptions ( ifstream::failbit ); 68 | try 69 | { 70 | fin.open(argv[1]); 71 | fcin = &fin; 72 | filename = argv[1]; 73 | } 74 | catch (std::ifstream::failure &e) 75 | { 76 | cout << "Exception opening/reading file: " << argv[1] << "\n"; 77 | usage(); 78 | exit(-1); 79 | } 80 | fin.exceptions(oldstate); 81 | } 82 | else 83 | { 84 | fcin = &cin; 85 | filename = "stdin"; 86 | } 87 | 88 | std::string conffilename; 89 | if(argc == 3) 90 | { 91 | conffilename = std::string(argv[2]); 92 | } 93 | 94 | #ifdef WIN32 95 | char buf[1000]; 96 | _getcwd(buf, 1000); 97 | string cwd(buf); 98 | #else 99 | string cwd; 100 | for (unsigned int bufsize = 1000; bufsize < PATH_MAX; bufsize*=2) 101 | { 102 | char buf[bufsize]; 103 | if (getcwd(buf, bufsize) != 0 || errno != ERANGE) 104 | { 105 | cwd = buf; 106 | break; 107 | } 108 | } 109 | #endif 110 | 111 | string::size_type found = 0; 112 | found = filename.find(cwd); 113 | if(found!=string::npos) 114 | { 115 | filename = filename.substr(cwd.size()+1); 116 | } 117 | RunMode runMode; 118 | MFileScanner scanner(*fcin, cout, filename, conffilename, runMode); 119 | scanner.execute(); 120 | return 0; 121 | } 122 | 123 | /* vim: set et sw=2 ft=ragel foldmethod=marker: */ 124 | 125 | -------------------------------------------------------------------------------- /src/confscanner.h: -------------------------------------------------------------------------------- 1 | #ifndef CONFSCANNER_H_ 2 | 3 | #define CONFSCANNER_H_ 4 | 5 | #include 6 | #include 7 | #include 8 | #include 9 | #include 10 | #include 11 | #include 12 | #include 13 | 14 | // 160 KB 15 | #define BUFSIZE 100*16384 16 | 17 | class ConfFileScanner { 18 | private: 19 | typedef std :: vector< std :: string > DocuBlock; 20 | typedef std :: map< std :: string, DocuBlock > DocuList; 21 | typedef std :: map< std :: string, DocuList > DocuListMap; 22 | typedef std :: set< std :: string > GroupSet; 23 | typedef std :: vector< std :: string > GlobList; 24 | typedef std :: map< std :: string, GlobList > GlobListMap; 25 | typedef std :: vector< GlobList > GlobListStack; 26 | 27 | 28 | public: 29 | ConfFileScanner(const std::string & filename, const std::string & conffilename); 30 | 31 | virtual ~ConfFileScanner() 32 | { 33 | delete buf; 34 | } 35 | 36 | int execute(); 37 | 38 | const char * get_conffile(); 39 | 40 | public: 41 | DocuList param_list_; 42 | DocuList return_list_; 43 | DocuListMap field_docu_; 44 | DocuBlock docuheader_; 45 | DocuBlock docubody_; 46 | DocuBlock docuextra_; 47 | GroupSet groupset_; 48 | DocuList vars_; 49 | 50 | private: 51 | 52 | void check_glob_level_up(); 53 | 54 | void go_level_down(); 55 | 56 | bool check_for_match(int l, const char * str); 57 | 58 | 59 | bool check_glob_rec(int l, const std::string & s); 60 | 61 | void cerr_stack() 62 | { 63 | for (unsigned int i = 0; i < globlist_stack_.size(); i++) { 64 | if (!globlist_stack_[i].empty()) { 65 | std::cerr << globlist_stack_[i][0] << " "; 66 | } 67 | } 68 | std::cerr << "current level: " << level_ << std::endl; 69 | std::cerr << "size of globlist_stack: " << globlist_stack_.size() << std::endl; 70 | std::cerr << std::endl; 71 | } 72 | 73 | void clear_all() 74 | { 75 | param_list_.clear(); 76 | return_list_.clear(); 77 | field_docu_.clear(); 78 | docuheader_.clear(); 79 | docubody_.clear(); 80 | docuextra_.clear(); 81 | groupset_.clear(); 82 | } 83 | 84 | private: 85 | /* ragel scanner variables */ 86 | char *buf; 87 | int line , col; 88 | int have; 89 | int cs; 90 | int top; 91 | int stack[30]; 92 | bool opt; 93 | 94 | /* references to data from the confscanner */ 95 | const std::string filename_; 96 | 97 | private: 98 | /* own data */ 99 | std::string conffile_; 100 | std::ifstream confistream_; 101 | 102 | int level_; 103 | bool arg_to_be_added_; 104 | bool match_at_level_[30]; 105 | DocuBlock *cblock_; 106 | DocuList *clist_; 107 | DocuListMap *clistmap_; 108 | GlobListMap globlist_map_; 109 | GlobListStack globlist_stack_; 110 | DocuBlock *arglist_; 111 | 112 | }; 113 | 114 | /* vim: set et sw=2: */ 115 | #endif /* CONFSCANNER_H_ */ 116 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | ====== 2 | MTOC++ 3 | ====== 4 | 5 | This somewhat larger project allows to create documentation for MatLab files 6 | and classes (including packages) using a doxygen_ filter named mtoc++. 7 | Moreover, a tool/class named ``MatlabDocMaker`` allows to create the documentation 8 | from within MatLab. For Windows, Mac and Unix! 9 | 10 | The project is also hosted on the `Mathworks File Exchange`_. 11 | 12 | Rough feature list 13 | ================== 14 | 15 | - Supports classes and packages 16 | - Also @folders for classes 17 | - Abstract & Static methods 18 | - Special tags "@type" and "@default" for method parameters and return values 19 | for more expressive documentation 20 | - Automatic detection of used fields and appropriate documentation 21 | - Default documentation for methods, parameters, return values etc 22 | - detection of getter & setter methods 23 | - included latex support and shortcuts for higher readability in plain text 24 | (e.g. `\sqrt{x}` is like @f$\sqrt{x}@f$) 25 | - support for MatLab events 26 | - HTML and LaTeX output 27 | - much more... 28 | 29 | Documentation 30 | ============= 31 | 32 | The complete documentation can be found at `here 33 | `_, but is also 34 | included in the download. Detailed instructions for installation and 35 | configuration can be found therein, however, here are the basic steps needed to 36 | get started: 37 | 38 | Installation 39 | ============ 40 | 41 | Unix / MAC OS 42 | ------------- 43 | 44 | - download & unzip in a folder. 45 | 46 | .. code:: bash 47 | 48 | tar xzf mtocpp.tar.gz 49 | .. 50 | 51 | - Create a ``build`` folder inside and change to that dir 52 | 53 | .. code:: bash 54 | 55 | mkdir build; cd build 56 | .. 57 | 58 | - Compile the source code 59 | 60 | .. code:: bash 61 | 62 | cmake .. 63 | make 64 | .. 65 | 66 | - You can find the the executables ``mtocpp`` and ``mtocpp_post`` inside the 67 | ``build`` folder, the documentation in ``docs``. Optionally you can install the 68 | 69 | Windows 70 | ------- 71 | 72 | Binaries for MTOC++ are distributed through the official `download page`_. 73 | Unpack the archive and add the binaries to your ``PATH``. 74 | 75 | 76 | Usage 77 | ===== 78 | 79 | 1. Place the ``MatlabDocMaker.m`` in your project's MatLab path 80 | 81 | 2. Copy the contents of the ``/tools/config`` folder into 82 | e.g. a subfolder of your MatLab project 83 | 84 | 3. place binaries (win or unix) on PATH environment or inside the folder 85 | created in the last step 86 | 87 | 4. Call the MatlabDocMaker.setup method and use the folder from the previous steps as your "documentation configuration files directory". 88 | 89 | 5. Use the MatlabDocMaker.create method to create your documentation! 90 | 91 | Developers 92 | ---------- 93 | 94 | Martin Drohmann and `Daniel Wirtz`_ 95 | 96 | We welcome any improvement suggestions and critics. 97 | 98 | .. _Mathworks File Exchange: http://www.mathworks.com/matlabcentral/fileexchange/33826-mtoc++-doxygen-filter-for-matlab-and-tools 99 | .. _doxygen: http://www.doxygen.org 100 | .. _download page: http://www.morepas.org/software/mtocpp/docs/download.html 101 | .. _Daniel Wirtz: http://www.mechbau.uni-stuttgart.de/ls2/jrg/people/academic_staff/wirtz/ 102 | -------------------------------------------------------------------------------- /src/docs/+examples/InheritedClass.m: -------------------------------------------------------------------------------- 1 | classdef InheritedClass < Class 2 | % Doxygen documentation guidelines example subclass 3 | % 4 | % To refer to other classes / methods / properties in superclasses one 5 | % can use the @@copydoc, @@copybrief and @@copydetail doxygen 6 | % commands. 7 | % For example the brief description of the superclass is: 8 | % @copybrief Class 9 | % 10 | % Here could be some additional information regarding the subclass. 11 | % 12 | % @new{0,1,dw,2011-03-17} Added this subclass to extend the 13 | % documentation examples. 14 | 15 | properties 16 | % New property in subclass! 17 | % 18 | % Detailed comment for SomeProp. Here you can write more detailed 19 | % text for the SomeProp property. 20 | % 21 | % @type integer @default 0 22 | SomeProp = 0; 23 | end 24 | 25 | properties(Dependent) 26 | % Short description for a dependent property. 27 | % 28 | % Equals SomeProp times five. 29 | % 30 | % @type integer @default 0 31 | % 32 | % See also: SomeProp 33 | % @see SomeProp 34 | SomeDepProp; 35 | end 36 | 37 | 38 | methods 39 | function returnarg = iwillbeoverridden(this, arg1, arg2) 40 | % Overrides the method in the base class. 41 | % 42 | % @copydetails 43 | % 44 | % With the command 45 | % @code 46 | % @copydetails Class::iwillbeoverridden() 47 | % @endcode 48 | % or 49 | % @code 50 | % @copydoc Class::iwillbeoverridden() 51 | % @endcode 52 | % the documentation of the superclass method can be copied 53 | % to this location (red framed) 54 | %
55 | % @copydetails Class::iwillbeoverridden() 56 | %
57 | % 58 | % Parameters: 59 | % arg1: of type sparsematrix 60 | % arg2: further documentation is ignored because of 61 | % @@copydoc/@@copydetails command 62 | % 63 | % Return values: 64 | % returnarg: The return value. @type matrix 65 | 66 | % Call superclass method 67 | returnarg = iwillbeoverridden@Class(this, arg1); 68 | 69 | % Do some more computations 70 | returnarg = returnarg + 10; 71 | end 72 | end 73 | 74 | methods(Sealed,Access=private) 75 | function noRealArguments(this) 76 | % This is the function brief description. 77 | % 78 | % Here are more details on the no real arguments function. 79 | % And even some more! 80 | % 81 | % The first argument corresponds to the auto-included object self-reference and is not processed but removed by mtoc++. 82 | end 83 | end 84 | 85 | methods(Access=?Class) 86 | function mySpecClassFun(a, b) 87 | % You can also define methods that may be accessed by specific classes. 88 | 89 | % do something 90 | end 91 | 92 | function mySpecClassFun2(a, b) 93 | % You can also define methods that may be accessed by specific classes. 94 | 95 | % Do even more. 96 | end 97 | end 98 | 99 | % This can be mixed.. 100 | properties(SetAccess=?example.Class, GetAccess='protected') 101 | % You can also mix the access restrictions. 102 | % Note the "note" tag below. 103 | % 104 | % @type integer 105 | VerySpecificProperty; 106 | end 107 | 108 | properties(SetAccess='private', GetAccess={?Class, ?example.Class}) 109 | % You can also specify multiple access restrictions in a cell array of metaclasses. 110 | % Note the "note" tag below. 111 | % 112 | % @type integer 113 | VerySpecificPropertyAccessibleByMoreClasses; 114 | end 115 | end 116 | 117 | -------------------------------------------------------------------------------- /tools/config/mtocpp.conf: -------------------------------------------------------------------------------- 1 | # ########################### mtoc++ configuration file ############################ 2 | # This configuration file is not mandatory. 3 | # All default values are also hardcoded in mtocpp. 4 | 5 | # ########################### mtoc++ variables ############################ 6 | # File Patterns 7 | ALL := *.m; 8 | 9 | # Flag indicating whether automatic struct fields or object members 10 | # documentation is generated. 11 | # The fields documentation types are 12 | # - required fields, 13 | # - optional fields and 14 | # - generated fields. 15 | # PRINT_FIELDS := true; 16 | 17 | # Flag indicating whether undocumented field names are added to documentation 18 | # with documentation text equal to the field name. 19 | # AUTO_ADD_FIELDS := false; 20 | 21 | # Flag indicating whether undocumented parameters and return values are added 22 | # to documentation with documentation text equal to the parameter / return 23 | # value name. 24 | # AUTO_ADD_PARAMETERS := false; 25 | 26 | # Flag indicating whether undocumented member variables are added to 27 | # documentation with documentation text equal to the parameter / return value 28 | # name. 29 | # AUTO_ADD_CLASS_PROPERTIES := false; 30 | 31 | # Flag indicating whether undocumented classes are added to documentation with 32 | # documentation text equal to the class name. 33 | # AUTO_ADD_CLASSES := true; 34 | 35 | # Flag indication whether the first argument in abstract non-static methods 36 | # shall be a this pointer, and therefore removed in the C++ output. 37 | # REMOVE_FIRST_ARG_IN_ABSTRACT_METHODS := true 38 | 39 | # Flag indicating whether the string "of type" is parsed in the the first two 40 | # lines 41 | # - of the documentation header of properties and 42 | # - the documentation block of method/function parameters and return values. 43 | # If enabled, the word following the string "of type" is interpreted as the 44 | # type for the class property, the parameter or the return value. This 45 | # equivalent to using the mtocpp @type keyword, but enables the user to write 46 | # documentation also read-able in doc strings created with the MATLAB commands 47 | # 'help' or 'doc'. 48 | # ENABLE_OF_TYPE_PARSING := true; 49 | 50 | # Flag indicating whether the typename void shall be inserted for return values 51 | # with no specified type. If this is not set to true, the typename is 52 | # eliminated in the output by the postprocessor. 53 | # VOID_TYPE_IN_RETURN_VALUES := false; 54 | 55 | # Integer flag indicating whether return value names shall be printed in the 56 | # function synopsis. If this flag is deactivated only the type names are 57 | # written. 58 | # The flag can be set to either 0, 1 or 2: 59 | # - 0: means that no return value names shall be printed at all. 60 | # - 1: means that return value names shall be printed for return value lists 61 | # with more than one element only. 62 | # - 2: means that return value names shall be printed always. 63 | # PRINT_RETURN_VALUE_NAME := 2; 64 | 65 | # Flag indicating whether the documentation of fields in 'Required fields of param', 66 | # 'Optional fields of param' or 'Generated fields of retval' shall be copied, 67 | # in case the Parameter 'param' or 'retval' have a type. 68 | # COPY_TYPIFIED_FIELD_DOCU := false; 69 | 70 | # Flag indicating whether documentation for subfunctions shall be generated. 71 | # By default their documentation strings are ignored. 72 | # GENERATE_SUBFUNTION_DOCUMENTATION := false; 73 | 74 | # Leave this ## there, it marks the end of variable definitions 75 | # and switches the parser to mtoc++ rules! 76 | ## 77 | 78 | # ########################### mtoc++ rules ############################ 79 | 80 | # ############################################################### 81 | # Default documentation for parameters 82 | # ############################################################### 83 | # Syntax: 84 | # add(params) = => """ """; 85 | 86 | # ############################################################### 87 | # Default documentation for fields 88 | # ############################################################### 89 | # Syntax: 90 | # add(fields) = ( . => """ """, 91 | # . => """ """); 92 | 93 | # ############################################################### 94 | # Global group settings 95 | # ############################################################### 96 | # Syntax: 97 | # glob = { 98 | # groups = ; 99 | # add(doc) = """ """; 100 | # add(extra) = """ """; 101 | # glob = { 102 | # 103 | # }; 104 | # } 105 | 106 | # add(doc) = """ docu for all functions !!! """; 107 | # add(extra) = """ extra comments: @ref s_rand !!!! """; 108 | -------------------------------------------------------------------------------- /test/test/+grid/+rect/doxygen_in_namespace.m: -------------------------------------------------------------------------------- 1 | function rv = doxygen(param1, param2, auto_param) 2 | % function rv = doxygen(param1, param2) is ignored 3 | % Here comes a short description text 4 | % 5 | % After the first empty documentation line, paragraphs of the detailed 6 | % description begin. 7 | % 8 | % Here, you have the following formatting possibilites: 9 | % Adding LaTeX code in the text with \verbatim @f$ \sum_{n=0}^N \frac{1}{n} @f$ \endverbatim 10 | % @f$ \sum_{n=0}^N \frac{1}{n} @f$ or as an 11 | % equation block with @verbatim @f[ \sum_{n=0}^N \frac{1}{n}. @f] @endverbatim. 12 | % @f[ \sum_{n=0}^N \frac{1}{n}. @f] Doxygen commands 13 | % always begin with an at-character(\@) OR a backslash(\\). 14 | % 15 | % Words prepended by \\c are written in a \c type-writer font. 16 | % Words prepended by \\b are written in a \b bold font. 17 | % Words prepended by \\em are written in an \em emphasized font. 18 | % 19 | % Blocks starting with @@verbatim or @@code and are ended with @@endverbatim or 20 | % @@endcode are written unformatted in a type-writer font and are not 21 | % interpreted by doxygen. 22 | % 23 | % Example: 24 | % @verbatim 25 | % /| |\ 26 | % ( |-| ) 27 | % ) " ( 28 | % (>(Y)<) 29 | % ) ( 30 | % / \ 31 | % ( (m|m) ) hjw 32 | % ,-.),___.(,-.\`97 33 | % \`---\' \`---\' 34 | % @endverbatim 35 | % 36 | % Paragaphs starting with line ending with a double-colon: 37 | % are started with a bold title line 38 | % 39 | % If, however, a double-colon at the end of a line is succeeded by: 40 | % whitespace characters, like spaces or tabulators the line is not written in a 41 | % bold font. 42 | % 43 | % @note As regularly commands like @verbatim \c @f$, @f$ @f[, @f] @endverbatim 44 | % look too distracting in matlab documentation output, the following shortcust 45 | % exist: The doxygen filter translates 46 | % - @verbatim 'word' to \c word @endverbatim resulting in the output: 'word', 47 | % - @verbatim `x` to @f$x@f$ @endverbatim resulting in the output: `x` and 48 | % - @verbatim ``x`` to @f[x.@f] @endverbatim resulting in the output: ``x``. 49 | % 50 | % You therefore need to be careful with the use of characters @verbatim ' ` 51 | % @endverbatim. If you want to say something about the transposed of a Matrix 52 | % 'A', better do it in a Tex-Environment as `A' * B'` or in a verbatim/code 53 | % environment as 54 | % @code A' * B' @endcode 55 | % 56 | % Listings can be added by prepending lines with a dash(-) 57 | % - list 1 item which can also include 58 | % newlines 59 | % - list 2 item 60 | % - and they can be nested 61 | % - subitem 2 62 | % . 63 | % - list 3 item 64 | % 65 | % and they are ended by an empty documentation line. 66 | % 67 | % Enumerations can be added by prepending lines with a dash and hash (-#) 68 | % -# first item 69 | % -# second item 70 | % -# third item 71 | % 72 | % Lines beginning with the words "Parameters" or "Return values" start a block 73 | % of argument respectively return argument descriptions. 74 | % 75 | % Parameters: 76 | % param1: first parameter 77 | % 78 | % Return values: 79 | % rv: return value 80 | % 81 | % A line beginning with the words "Required fields of", "optional fields of" or 82 | % "generated fields of" start a block for descriptions for fields used by the 83 | % parameters or generated for the return values. 84 | % 85 | % Required fields of param1: 86 | % test: Description for required field param1.test 87 | % 88 | % Optional fields of param2: 89 | % test2: Description for optional field param2.test2 90 | % 91 | % Generated fields of rv: 92 | % RB: Description for generated field rv.RB 93 | % 94 | % 95 | 96 | % After the first non-comment line the function body begins: 97 | 98 | %| Comment blocks starting with %| are interpreted as Doxygen documentation 99 | % blocks and can include doxygen commands like 100 | 101 | %| \todo There needs to be done something in this file 102 | 103 | % fields of parameters that are used in the function body are added to the 104 | % required fileds list automatically, if they are not documentated yet. 105 | param1.auto_added; 106 | 107 | param2.auto_added; 108 | 109 | % fields of return values that are assigned somewhere in the function body are 110 | % also added automatically to the list of generated fields 111 | rv.auto_added = 1; 112 | rv.sub.auto_added = 2; 113 | 114 | param1.sub.auto_added; 115 | 116 | auto_param.auto_field; 117 | 118 | function c=second_function_without_docu(a,b) 119 | 120 | function [d,e,f]=third_function_with_sev_retvals(auto_param) 121 | % a third (private) function in the test file with serveral return values 122 | % 123 | % Return values: 124 | % d : a return value 125 | 126 | function [d,e,f]=third_function_without_parameters 127 | % function [d,e,f]=third_function_without_parameters 128 | % a third (private) function in the test file without parameters 129 | % 130 | % Return values: 131 | % d : a return value 132 | 133 | %| \docupdate 134 | -------------------------------------------------------------------------------- /test/doxygen.m: -------------------------------------------------------------------------------- 1 | function rv = doxygen(param1, param2, auto_param) 2 | % function rv = doxygen(param1,... 3 | % param2,...) is ignored 4 | % Here comes a short description text 5 | % 6 | % After the first empty documentation line, paragraphs of the detailed 7 | % description begin. 8 | % 9 | % Here, you have the following formatting possibilites: 10 | % Adding LaTeX code in the text with \verbatim @f$ \sum_{n=0}^N \frac{1}{n} @f$ \endverbatim 11 | % @f$ \sum_{n=0}^N \frac{1}{n} @f$ or as an 12 | % equation block with @verbatim @f[ \sum_{n=0}^N \frac{1}{n}. @f] @endverbatim. 13 | % @f[ \sum_{n=0}^N \frac{1}{n}. @f] Doxygen commands 14 | % always begin with an at-character(\@) OR a backslash(\\). 15 | % 16 | % Words prepended by \\c are written in a \c type-writer font. 17 | % Words prepended by \\b are written in a \b bold font. 18 | % Words prepended by \\em are written in an \em emphasized font. 19 | % 20 | % Chinese character: 書 21 | % 22 | % Blocks starting with @@verbatim or @@code and are ended with @@endverbatim or 23 | % @@endcode are written unformatted in a type-writer font and are not 24 | % interpreted by doxygen. 25 | % 26 | % Example: 27 | % @verbatim 28 | % /| |\ 29 | % ( |-| ) 30 | % ) " ( 31 | % (>(Y)<) 32 | % ) ( 33 | % / \ 34 | % ( (m|m) ) hjw 35 | % ,-.),___.(,-.\`97 36 | % \`---\' \`---\' 37 | % @endverbatim 38 | % 39 | % Paragaphs starting with line ending with a double-colon: 40 | % are started with a bold title line 41 | % 42 | % If, however, a double-colon at the end of a line is succeeded by: 43 | % whitespace characters, like spaces or tabulators the line is not written in a 44 | % bold font. 45 | % 46 | % @note As regularly commands like @verbatim \c @f$, @f$ @f[, @f] @endverbatim 47 | % look too distracting in matlab documentation output, the following shortcust 48 | % exist: The doxygen filter translates 49 | % - @verbatim 'word' to \c word @endverbatim resulting in the output: 'word', 50 | % - @verbatim `x` to @f$x@f$ @endverbatim resulting in the output: `x` and 51 | % - @verbatim ``x`` to @f[x.@f] @endverbatim resulting in the output: ``x``. 52 | % 53 | % You therefore need to be careful with the use of characters @verbatim ' ` 54 | % @endverbatim. If you want to say something about the transposed of a Matrix 55 | % 'A', better do it in a Tex-Environment as `A' * B'` or in a verbatim/code 56 | % environment as 57 | % @code A' * B' @endcode 58 | % 59 | % Listings can be added by prepending lines with a dash(-) 60 | % - list 1 item which can also include 61 | % newlines 62 | % - list 2 item 63 | % - and they can be nested 64 | % - subitem 2 65 | % . 66 | % - list 3 item 67 | % 68 | % and they are ended by an empty documentation line. 69 | % 70 | % Enumerations can be added by prepending lines with a dash and hash (-#) 71 | % -# first item 72 | % -# second item 73 | % -# third item 74 | % 75 | % Lines beginning with the words "Parameters" or "Return values" start a block 76 | % of argument respectively return argument descriptions. 77 | % 78 | % Parameters: 79 | % param1: first parameter of type testnamespace.testclass. 80 | % auto_param: of type ::gridbase 81 | % 82 | % Return values: 83 | % rv: return value 84 | % 85 | % A line beginning with the words "Required fields of", "optional fields of" or 86 | % "generated fields of" start a block for descriptions for fields used by the 87 | % parameters or generated for the return values. 88 | % 89 | % Required fields of param1: 90 | % test: Description for required field param1.test 91 | % 92 | % Optional fields of param2: 93 | % test2: Description for optional field param2.test2 94 | % 95 | % Generated fields of rv: 96 | % RB: Description for generated field rv.RB 97 | % 98 | % 99 | 100 | % After the first non-comment line the function body begins: 101 | 102 | %| Comment blocks starting with %| are interpreted as Doxygen documentation 103 | % blocks and can include doxygen commands like 104 | 105 | %| \todo There needs to be done something in this file 106 | 107 | % fields of parameters that are used in the function body are added to the 108 | % required fileds list automatically, if they are not documentated yet. 109 | param1.auto_added; 110 | 111 | %@@remove 112 | % test 113 | param2.auto_added; 114 | %@@endremove 115 | 116 | % fields of return values that are assigned somewhere in the function body are 117 | % also added automatically to the list of generated fields 118 | rv.auto_added = 1; 119 | rv.sub.auto_added = 2; 120 | 121 | param1.sub.auto_added; 122 | 123 | auto_param.auto_field; 124 | 125 | function c=second_function_without_docu(a,b) 126 | 127 | function [d,e,f]=third_function_with_sev_retvals(~, auto_param, ~, ~) 128 | % a third (private) function in the test file with serveral return values 129 | % 130 | % Parameters: 131 | % auto_param: @type ::rectgrid 132 | % 133 | % Return values: 134 | % d : a return value 135 | 136 | function totally_ignored_subfunction(a, b, c) 137 | % documentation string for the totally ignored subfunction 138 | end 139 | 140 | body(string, with, double quote, and percent sign, ' "%s"}') % a real comment } 141 | 142 | function [~ , d, ~, ~]=third_function_without_parameters 143 | % function [~ , d,e,f]=third_function_without_parameters 144 | % a third (private) function in the test file without parameters 145 | % 146 | % Return values: 147 | % d : a return value 148 | 149 | function default_parameters(uml, open) 150 | % function default_parameters(uml, open) 151 | % function with two default parameters 152 | % 153 | % Parameters: 154 | % uml: Set to true to create UML-like graphics output 155 | % @type bool @default false 156 | % open: Set to true if the documentation should be opened after 157 | % successful compilation 158 | % @type bool @default [1;2;3] 159 | 160 | function default_parameters2(uml, open) 161 | % function default_parameters(uml, open) 162 | % function with two default parameters 163 | % 164 | % Parameters: 165 | % uml: Set to true to create UML-like graphics output 166 | % @default false @type bool 167 | % open: Set to true if the documentation should be opened after 168 | % successful compilation 169 | % @type bool 170 | 171 | 172 | %| \docupdate 173 | -------------------------------------------------------------------------------- /src/docs/changelist.c: -------------------------------------------------------------------------------- 1 | /** 2 | * @page changes Changes and new features in mtoc++ 3 | * @short Changelog and new feature list for mtoc++ 4 | * 5 | * Here are all the changes/new features sorted by versions of mtoc++: 6 | * - @subpage newfeat0_1 - @subpage changelog0_1 7 | * - @subpage newfeat1_2 - @subpage changelog1_2 8 | * - @subpage newfeat1_3 - @subpage changelog1_3 9 | * - @subpage newfeat1_4 - @subpage changelog1_4 10 | * - @subpage newfeat1_5 - @subpage changelog1_5 11 | * 12 | * @attention The repeated occurence of the new features/changes in this 13 | * specific site below is just due to the fact that the mtoc++ features/changes 14 | * themselves have to be written down somewhere. Under usual circumstances 15 | * those tags below would be placed inside the MatLab files/functions/classes 16 | * where the actual change happened; see the comments from the MatlabDocMaker 17 | * as an example. So the list below is not necessarily complete, but the sites 18 | * referenced above contain all new features / changes! 19 | * 20 | * @new{1,5,dw,2013-07-22} Added a FAQ: @ref faq 21 | * 22 | * @change{1,5,dw,2013-06-25} mtocpp_post/postprocess.rl: Increased robustness. If processing a directory, 23 | * the postprocessor does not completely stop on (rare) parse errors but continues to loop through the directory. 24 | * This way all files are at least tried to be processed. 25 | * 26 | * @new{1,5,dw,2013-02-21} Added '*.mex' files to the types of files parsed by default in Doxyfile.template 27 | * 28 | * @change{1,4,dw,2012-11-19} mtocpp_post/postprocess.rl: Re-Added the possibility to directly specify a file target instead of a whole folder. 29 | * 30 | * @change{1,4,dw,2012-10-17} 31 | * - Using the new css-style from doxygen 1.8 for own docs 32 | * - Added some troubleshooting feedback 33 | * - Checked the CMake procedure on a Mac platform (MacBook pro), worked neatly. 34 | * - Added an extra section @ref tools_direct for instructions on how to directly use mtoc++ 35 | * - Fixed broken links to MatLab method/property attributes in mtoc++ output 36 | * 37 | * @change{1,4,dw,2012-09-27} Optimized compilation under Visual Studio 2010, now can also build the mtoc++ documentation locally. 38 | * 39 | * @change{1,4,md,2012-09-27} 40 | * - Added check for HAVE_DOT in doxygen.conf.in 41 | * - Bugfix for function-only M-files reported by Francois Rongere 42 | * 43 | * @new{1,4,md,2012-02-17} 44 | *- Started mtoc++ 1.4. 45 | *- Added alias for an "events" tag, creating a page of all events in default documentation 46 | *- Changed naming convention for alias-tags new and change as newer doxygen 47 | * versions seem not to recognize \1\2-like combinations of arguments any more (?) 48 | * now pages named "newfeat\1_\2" with underscore are created, please update your static 49 | * references in your misc documentation files 50 | * 51 | * @change{1,3,dw,2012-01-16} Changed the \c SHOW_FILES default value in the 52 | * doxygen configuration file from "NO" to "YES". 53 | * 54 | * @change{1,3,dw,2012-01-16} Bugfix: The setting \c EXTRA_PACKAGES in the 55 | * doxygen configuration file was given the wrong path format, as latex follows 56 | * the unix file separation using only forwardslashes "/", so the inclusion 57 | * failed on Windows platforms. We fixed this by passing the correctly 58 | * transformed path. Also a new placeholder "_FileSep_" which is being 59 | * processed by MatlabDocMaker (any any tools to come) and set to the correct 60 | * file separator character for your platform. 61 | * 62 | * @change{1,3,dw,2012-01-14} Bugfix: Moved the mtoc++ developers page 63 | * declaration into a separate file inside the tools/config folder, so that 64 | * error messages like "changelog1:13: warning: unable to resolve reference to 65 | * `dw' for \ref command" do not appear anymore. 66 | * 67 | * @change{1,3,dw,2011-12-08} Bugfix: The CUSTOM_DOC_DIR path is not longer 68 | * extended by a \c docs/ folder. 69 | * 70 | * @change{1,3,dw,2011-11-29} Added the new fake classes varargin and varargout 71 | * to the class_substitutes.c file with links to the MatLab online 72 | * documentation. 73 | * 74 | * @new{1,3,dw,2011-11-28} Started mtoc++ 1.3. 75 | * 76 | * @new{1,2,dw,2011-11-27} Reordered the Doxyfile.m4 so that changes from our 77 | * side are all collected to the bottom. This makes keeping custom settings 78 | * over different versions easier. 79 | * 80 | * @new{1,2,dw,2011-11-25} Included a file class_substitutes.c into the config 81 | * directory that introduces fake classes for common matlab data types. 82 | * 83 | * @change{1,2,md,2011-11-17} Updated the test reference files 84 | * 85 | * @new{1,2,dw,2011-11-07} Created the initial mtoc++ documentation structure 86 | * 87 | * @change{1,2,dw,2011-11-07} Reordered the source code files and tools in more 88 | * concise folders. 89 | * 90 | * @page newfeat0_1 New features in mtoc++ 0.1 91 | * @short Demo features of the demo classes and examples 92 | * 93 | * See also @ref changelog0_1 94 | * 95 | * @page changelog0_1 Changes in mtoc++ 0.1 96 | * @short Demo changes of the demo classes and examples 97 | * 98 | * See also @ref newfeat0_1 99 | * 100 | * @page newfeat1_2 New features in mtoc++ 1.2 101 | * @short First "stable" release with windows/unix support. 102 | * 103 | * See also @ref changelog1_2 104 | * 105 | * 106 | * @page changelog1_2 Changes in mtoc++ 1.2 107 | * @short First "stable" release with windows/unix support. 108 | * 109 | * See also @ref newfeat1_2 110 | * 111 | * @page newfeat1_3 New features in mtoc++ 1.3 112 | * @short Improved stability for Windows platforms, event handling 113 | * 114 | * See also @ref changelog1_3 115 | * 116 | * @page changelog1_3 Changes in mtoc++ 1.3 117 | * @short Improved stability for Windows platforms, event handling 118 | * 119 | * See also @ref newfeat1_3 120 | * 121 | * @page newfeat1_4 New features in mtoc++ 1.4 122 | * @short Included basic source browsing, handling of varargin-parameters, basic LaTeX generation support 123 | * 124 | * See also @ref changelog1_4 125 | * 126 | * @page changelog1_4 Changes in mtoc++ 1.4 127 | * @short Many bugfixes due to detailed feedback! Thanks! 128 | * 129 | * See also @ref newfeat1_4 130 | * 131 | * @page newfeat1_5 New features in mtoc++ 1.5 132 | * @short Current development 133 | * 134 | * See also @ref changelog1_5 135 | * 136 | * @page changelog1_5 Changes in mtoc++ 1.5 137 | * @short Current development 138 | * 139 | * See also @ref newfeat1_5 140 | */ 141 | -------------------------------------------------------------------------------- /src/docs/DoxygenLayout.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 180 | 181 | 182 | 183 | 184 | -------------------------------------------------------------------------------- /tools/config/class_substitutes.c: -------------------------------------------------------------------------------- 1 | /** 2 | * @class rowvec 3 | * @brief A matlab row vector. 4 | * 5 | * This class is an artificially created class in doxygen to allow more precise type declarations 6 | * 7 | * @class colvec 8 | * @brief A matlab column vector. 9 | * 10 | * This class is an artificially created class in doxygen to allow more precise type declarations 11 | * 12 | * @class integer 13 | * @brief An integer value 14 | * 15 | * This class is an artificially created class in doxygen to allow more precise type declarations. 16 | * Matlab types associated with this class are all int-types (int8, uint8 etc). 17 | * 18 | * @class double 19 | * @brief A double value 20 | * 21 | * This class is an artificially created class in doxygen to allow more precise type declarations. 22 | * The MatLab type associated with this class is double. 23 | * 24 | * @class logical 25 | * @brief A boolean value 26 | * 27 | * This class can be seen as synonym for boolean values/flags used inside classes. In order to stick with 28 | * matlab conventions/datatypes, this class was named logical instead of bool or boolean. 29 | * 30 | * This class is an artificially created class in doxygen to allow more precise type declarations 31 | * 32 | * @class function_handle 33 | * @brief A MatLab function handle 34 | * 35 | * This class is an artificially created class in doxygen to allow more precise type declarations 36 | * 37 | * @class char 38 | * @brief A MatLab character array 39 | * 40 | * This class is an artificially created class in doxygen to allow more precise type declarations 41 | * and represents string-like types. 42 | * 43 | * @class cell 44 | * @brief A MatLab cell array or matrix 45 | * 46 | * This class is an artificially created class in doxygen to allow more precise type declarations 47 | * 48 | * @class struct 49 | * @brief A MatLab struct 50 | * 51 | * This class is an artificially created class in doxygen to allow more precise type declarations 52 | * 53 | * @class varargin 54 | * @brief A variable number of input arguments 55 | * 56 | * This class is an artificially created class in doxygen to allow more precise type declarations. 57 | * 58 | * For more information about the varargin argument see the 59 | * 60 | * MatLab documentation on varargin. 61 | * 62 | * 63 | * @class varargout 64 | * @brief A variable number of output arguments 65 | * 66 | * This class is an artificially created class in doxygen to allow more precise type declarations. 67 | * 68 | * For more information about the varargout argument see the 69 | * 70 | * MatLab documentation on varargout. 71 | */ 72 | 73 | class matrix { 74 | /** 75 | * @class matrix 76 | * @brief A matlab matrix 77 | * 78 | * This class is an artificially created class in doxygen to allow more precise type declarations 79 | */ 80 | }; 81 | class sparsematrix 82 | :public ::matrix { 83 | /** 84 | * @class sparsematrix 85 | * @brief A matlab sparse matrix 86 | * 87 | * This class is an artificially created class in doxygen to allow more precise type declarations 88 | */ 89 | }; 90 | 91 | class handle { 92 | /** 93 | @class handle 94 | @brief Matlab's base handle class (documentation generation substitute) 95 | 96 | As doxygen does not know the class "handle" from itself, many classes do not get rendered within the documentation and the correct root class is not even displayed. 97 | This workaround guarantees a correct (also graphical) representation of the class hierarchy. 98 | * 99 | * Note here that by having the type handle it could also mean to have a vector or matrix of handles. 100 | * 101 | */ 102 | public: 103 | /** @brief Creates a listener for the specified event and assigns a callback function to execute when the event occurs. 104 | * @sa notify 105 | */ 106 | matlabtypesubstitute addlistener; 107 | 108 | 109 | /** 110 | @brief Broadcast a notice that a specific event is occurring on a specified handle object or array of handle objects. 111 | */ 112 | matlabtypesubstitute notify; 113 | 114 | /** 115 | @brief Handle object destructor method that is called when the object's lifecycle ends. 116 | */ 117 | matlabtypesubstitute delete; 118 | 119 | /** 120 | @brief Handle object disp method which is called by the display method. See the MATLAB disp function. 121 | */ 122 | matlabtypesubstitute disp; 123 | 124 | /** 125 | @brief Handle object display method called when MATLAB software interprets an expression returning a handle object that is not terminated by a semicolon. See the MATLAB display function. 126 | */ 127 | matlabtypesubstitute display; 128 | 129 | /** 130 | @brief Finds objects matching the specified conditions from the input array of handle objects. 131 | */ 132 | matlabtypesubstitute findobj; 133 | 134 | /** 135 | @brief Returns a meta.property objects associated with the specified property name. 136 | */ 137 | matlabtypesubstitute findprop; 138 | 139 | /** 140 | @brief Returns a cell array of string containing the names of public properties. 141 | */ 142 | matlabtypesubstitute fields; 143 | 144 | /** 145 | @brief Returns a cell array of string containing the names of public properties. See the MATLAB fieldnames function. 146 | */ 147 | matlabtypesubstitute fieldnames; 148 | 149 | /** 150 | @brief Returns a logical array in which elements are true if the corresponding elements in the input array are valid handles. 151 | This method is Sealed so you cannot override it in a handle subclass. 152 | */ 153 | matlabtypesubstitute isvalid; 154 | 155 | /** 156 | @brief Relational functions example. See details for more information. 157 | 158 | @par Other possible relational operators: 159 | -ne 160 | -lt 161 | -le 162 | -gt 163 | -ge 164 | 165 | Relational functions return a logical array of the same size as the pair of input handle object arrays. Comparisons use a number associated with each handle. You can assume that the same two handles will compare as equal and the repeated comparison of any two handles will yield the same result in the same MATLAB session. Different handles are always not-equal. The order of handles is purely arbitrary, but consistent. 166 | */ 167 | matlabtypesubstitute eq; 168 | 169 | /** 170 | @brief Transposes the elements of the handle object array. 171 | */ 172 | matlabtypesubstitute transpose; 173 | 174 | /** 175 | @brief Rearranges the dimensions of the handle object array. See the MATLAB permute function. 176 | */ 177 | matlabtypesubstitute permute; 178 | 179 | /** 180 | @brief hanges the dimensions of the handle object array to the specified dimensions. See the MATLAB reshape function. 181 | */ 182 | matlabtypesubstitute reshape; 183 | 184 | /** 185 | @brief ort the handle objects in any array in ascending or descending order. 186 | 187 | The order of handles is purely arbitrary, but reproducible in a given MATLAB session. See the MATLAB sort function. 188 | */ 189 | matlabtypesubstitute sort; 190 | } 191 | -------------------------------------------------------------------------------- /test/classA.m: -------------------------------------------------------------------------------- 1 | % unnecessary comments in front of class 2 | 3 | classdef(Sealed=Initialize) classA < general.reference.classB & a.b.c & ... 4 | d.e.f ... 5 | & g.h.i ... 6 | & grid.rect.rectgrid; 7 | % help for classA 8 | % 9 | % bigger help for classA 10 | 11 | properties ( SetAccess = 'private', Access = ?Test, GetAccess = protected, Transient);% garbage comment 12 | 13 | mixed_access; % variable of type gridbase.gridbase storing a grid. 14 | 15 | % longer help with `default` value 16 | % what is this?? 17 | % 18 | % can we do some special stuff?? 19 | % @verbatim 20 | % a= b; 21 | % c= d; 22 | % @endverbatim 23 | mixed_access2 = 'test'; 24 | 25 | % This documentation is a test for the type keyword. 26 | % 27 | % This variable has a special type 28 | % @type SpecialType @default empty string 29 | DataStoreDirectory = ''; 30 | 31 | SomeProp = struct('xi',[],'ti',[],'mui',[]); 32 | 33 | SomeOtherProp = struct(... 34 | 'xi', [], 'ti', ... 35 | []); 36 | 37 | % variable with very long default value 38 | SteadyStates = [[0; 9.8153e-4; 0.1930]*models.pcd.BasePCDSystem.xa0... 39 | [0; 3.0824e-5; 0.1713]*models.pcd.BasePCDSystem.ya0... 40 | [.2; 0.1990; 0.0070]*models.pcd.BasePCDSystem.xi0... 41 | [.2; 0.2; 0.0287]*models.pcd.BasePCDSystem.yi0]; 42 | 43 | Property_without_semicolon % commented anyways 44 | 45 | end; % garbage comment 46 | 47 | properties (Constant, SetAccess = {?Test1, ?Test2}); % garbage comment 48 | aConstant = 1; % help text 49 | 50 | % help text for bConstant 51 | bConstant = 2; 52 | 53 | cConstant = 3; % help text for cConstant 54 | 55 | vectorConst = [ 1; 2; 3 ] 56 | 57 | % test 58 | dConstant = { [ 1, 2; 3, 4]; 'test'; [ 1 2; [ [3 [3 [3 4] 4] ] ] ] }; 59 | 60 | dConstant = struct('a', [], 'b', {'c', 'd'}, 'e', [1 2 3]); 61 | end 62 | 63 | properties 64 | public_access; % short help for public_access 65 | 66 | % longer help for public_access2 67 | public_access2; 68 | 69 | complexpropertywithoutsemicolon = [['af]adgdg' 70 | 'adgadg']] 71 | followingpropwithoutsemicolon = 4 72 | antoheroneWITH; 73 | 74 | % with comments version! 75 | complexpropertywithoutsemicolon_c = [['af]a"§/$"''dgdg' 76 | 'adgadg']] 77 | % with comments version! GRR 78 | followingpropwithoutsemicolon_c = 4 79 | % with comments version 80 | antoheroneWITH_c; 81 | end 82 | 83 | properties (Access = protected) 84 | protected_access; % short help for protected_access 85 | 86 | % longer help text for protected_access2 87 | protected_access2; 88 | end 89 | 90 | methods(Hidden = True); % garbage comment 91 | 92 | function obj = foo(a,b,c); 93 | % brief doc for foo 94 | 95 | function private_function 96 | 97 | pause; 98 | end 99 | 100 | bar; 101 | end; % garbage comment 102 | 103 | % comment 104 | % zweite Zeile 105 | 106 | function obj = bar(c,d,e); 107 | % brief doc for bar 108 | 109 | foo; 110 | end; 111 | 112 | % last function comment above 113 | % 114 | % with main docu block 115 | function obj = foobar() 116 | % brief for foobar 117 | % 118 | % detail for foobar 119 | 120 | test %boolean switch 121 | end %garbage comment 122 | 123 | % this is only a declaration without definition of a method 124 | ret=mdecl(a,b);;;;;;;; 125 | % this is only a declaration without definition of a method behind 126 | 127 | function obj = classA(param1, param2) 128 | % bigger constructor 129 | end; 130 | end; %garbage comment 131 | 132 | methods 133 | function value = get.protected_access(this) 134 | % getter enriching property help text of protected_access 135 | 136 | if a==b 137 | do something; 138 | % the following end needs to be indented correctly 139 | end % garble this correctly 140 | 141 | %| 142 | % \todo this is a test 143 | 144 | end 145 | 146 | function set.protected_access(this, value) 147 | % setter comment is parsed too 148 | 149 | a; 150 | end 151 | 152 | 153 | function set.DataStoreDirectory(this, ds) 154 | if ~isdir(ds) 155 | fprintf('Creating directory %s\n',ds); 156 | mkdir(ds); 157 | end 158 | setpref('KERMOR','DATASTORE',ds); 159 | this.DataStoreDirectory = ds; 160 | fprintf('Simulation and model data: %s\n',ds); 161 | end 162 | 163 | function set.protected_access2(this, value) 164 | 165 | a; 166 | end 167 | 168 | end 169 | 170 | methods (Static) ;;; % garbage comment 171 | function [a,b] = static_method(notthis,c,~) 172 | % a static method 173 | end 174 | 175 | function ret = test(auto_param,b,c) 176 | % @copybrief grid::rect::rectgrid::test() 177 | % 178 | % If copydetails/copydoc commands are used, "parameters" and "return 179 | % values" are ignored in the derived class, except for the strings 180 | % 'of type ...' which are used to define the parameter / return value 181 | % type. 182 | % 183 | % @copydetails grid::rect::rectgrid::test() 184 | % 185 | % Parameters: 186 | % b: second argument in derived class (this is not shown!) 187 | % c: object of type test2 188 | end 189 | end 190 | 191 | methods (Static, Abstract) 192 | % a static abstract method 193 | [a,b] = static_abstract_method(this, c), 194 | 195 | end 196 | 197 | methods (Abstract) 198 | 199 | % an abstract method comment above 200 | % 201 | % Parameters: 202 | % d: parameter 1 203 | % e: parameter 2 204 | % 205 | % Return values: 206 | % a: test object of type 207 | % classA.mixed_access which has a line break in it 208 | [a] = abstract_method(this,d,e); 209 | % an abstract method comment below 210 | % 211 | % further comments 212 | 213 | a = undocumented_abstract_method(t, b, f); 214 | 215 | [b,c,d] = another_undocumented_abstract_method(t, b, c); 216 | 217 | % documentation for next method 218 | c = followed_by_document_method(t, d, e); 219 | end 220 | 221 | methods(Access=?Class) 222 | function mySpecClassFun(a, b), 223 | % do something 224 | end 225 | 226 | function mySpecClassFun2(a, b) 227 | end 228 | end 229 | 230 | properties(SetAccess=?Class, GetAccess=private) 231 | % Comment! 232 | % 233 | % @type integer 234 | SomeFirstSpecialProp; 235 | end 236 | 237 | properties(SetAccess=?Class, GetAccess={?Class, ?example.Class}) 238 | % Comment! 239 | % 240 | % @type integer 241 | SomeSpecialProp; 242 | end 243 | 244 | % garbage comment 245 | properties(SetAccess='protected', GetAccess={?example.pkg.Class ?example.Class } ) 246 | % Comment! 247 | SomeSpecialProp2; 248 | 249 | % garbage comment 250 | end 251 | 252 | % garbage 253 | properties(SetAccess= { ?Class;... 254 | ?Foo ; ?some.package.Bar }, GetAccess={?Class, ... 255 | ?example.Class}) 256 | % Comment 2! 257 | SomeSpecialProp3; 258 | end 259 | 260 | events (Hidden=true, ListenAccess=private) 261 | 262 | % a documented event 263 | documentedEvent 264 | 265 | undocumentedEvent 266 | followingUndocumentedEvent; 267 | end 268 | 269 | end 270 | 271 | -------------------------------------------------------------------------------- /test/doxygen_in_namespace_ref.cc: -------------------------------------------------------------------------------- 1 | namespace grid{ 2 | namespace rect{ 3 | 4 | 5 | /* (Autoinserted by mtoc++) 6 | * This source code has been filtered by the mtoc++ executable, 7 | * which generates code that can be processed by the doxygen documentation tool. 8 | * 9 | * On the other hand, it can neither be interpreted by MATLAB, nor can it be compiled with a C++ compiler. 10 | * Except for the comments, the function bodies of your M-file functions are untouched. 11 | * Consequently, the FILTER_SOURCE_FILES doxygen switch (default in our Doxyfile.template) will produce 12 | * attached source files that are highly readable by humans. 13 | * 14 | * Additionally, links in the doxygen generated documentation to the source code of functions and class members refer to 15 | * the correct locations in the source code browser. 16 | * However, the line numbers most likely do not correspond to the line numbers in the original MATLAB source files. 17 | */ 18 | 19 | mlhsInnerSubst doxygen(matlabtypesubstitute param1,matlabtypesubstitute param2,::othergrid auto_param) { 20 | 21 | 22 | /* After the first non-comment line the function body begins: */ 23 | 24 | /** Comment blocks starting with %| are interpreted as Doxygen documentation 25 | * blocks and can include doxygen commands like */ 26 | 27 | /** \todo There needs to be done something in this file */ 28 | 29 | /* fields of parameters that are used in the function body are added to the 30 | * required fileds list automatically, if they are not documentated yet. */ 31 | param1.auto_added; 32 | 33 | param2.auto_added; 34 | 35 | /* fields of return values that are assigned somewhere in the function body are 36 | * also added automatically to the list of generated fields */ 37 | rv.auto_added= 1; 38 | rv.sub.auto_added= 2; 39 | 40 | param1.sub.auto_added; 41 | 42 | auto_param.auto_field; 43 | 44 | } 45 | /** @file "test/+grid/+rect/doxygen_in_namespace.m" 46 | * @ingroup test 47 | * @brief Here comes a short description text 48 | */ 49 | /** @fn mlhsInnerSubst doxygen(matlabtypesubstitute param1,matlabtypesubstitute param2,::othergrid auto_param) 50 | * @brief Here comes a short description text 51 | * 52 | * 53 | * After the first empty documentation line, paragraphs of the detailed 54 | * description begin. 55 | * 56 | * @par Here, you have the following formatting possibilites 57 | * Adding LaTeX code in the text with \verbatim @f$ \sum_{n=0}^N \frac{1}{n} @f$ \endverbatim 58 | * @f$ \sum_{n=0}^N \frac{1}{n} @f$ or as an 59 | * equation block with @verbatim @f[ \sum_{n=0}^N \frac{1}{n}. @f] @endverbatim. 60 | * @f[ \sum_{n=0}^N \frac{1}{n}. @f] Doxygen commands 61 | * always begin with an at-character(@) OR a backslash(\\). 62 | * 63 | * Words prepended by \\c are written in a \c type-writer font. 64 | * Words prepended by \\b are written in a \b bold font. 65 | * Words prepended by \\em are written in an \em emphasized font. 66 | * 67 | * Blocks starting with @@verbatim or @@code and are ended with @@endverbatim or 68 | * @@endcode are written unformatted in a type-writer font and are not 69 | * interpreted by doxygen. 70 | * 71 | * @par Example 72 | * @verbatim 73 | /| |\ 74 | ( |-| ) 75 | ) " ( 76 | (>(Y)<) 77 | ) ( 78 | / \ 79 | ( (m|m) ) hjw 80 | ,-.),___.(,-.\`97 81 | \`---\' \`---\' 82 | @endverbatim 83 | * 84 | * @par Paragaphs starting with line ending with a double-colon 85 | * are started with a bold title line 86 | * 87 | * If, however, a double-colon at the end of a line is succeeded by: 88 | * whitespace characters, like spaces or tabulators the line is not written in a 89 | * bold font. 90 | * 91 | * @note As regularly commands like @verbatim \c @f$, @f$ @f[, @f] @endverbatim 92 | * look too distracting in matlab documentation output, the following shortcust 93 | * exist: The doxygen filter translates 94 | * - @verbatim 'word' to \c word @endverbatim resulting in the output: word, 95 | * - @verbatim `x` to @f$x@f$ @endverbatim resulting in the output: @f$x@f$ and 96 | * - @verbatim ``x`` to @f[x.@f] @endverbatim resulting in the output: @f[x@f]. 97 | * 98 | * You therefore need to be careful with the use of characters @verbatim ' ` 99 | @endverbatim. If you want to say something about the transposed of a Matrix 100 | * A, better do it in a Tex-Environment as @f$A' * B'@f$ or in a verbatim/code 101 | * environment as 102 | * @code A' * B' @endcode 103 | * 104 | * Listings can be added by prepending lines with a dash(-) 105 | * - list 1 item which can also include 106 | * newlines 107 | * - list 2 item 108 | * - and they can be nested 109 | * - subitem 2 110 | * . 111 | * - list 3 item 112 | * 113 | * and they are ended by an empty documentation line. 114 | * 115 | * Enumerations can be added by prepending lines with a dash and hash (-#) 116 | * -# first item 117 | * -# second item 118 | * -# third item 119 | * 120 | * Lines beginning with the words "Parameters" or "Return values" start a block 121 | * of argument respectively return argument descriptions. 122 | * 123 | * A line beginning with the words "Required fields of", "optional fields of" or 124 | * "generated fields of" start a block for descriptions for fields used by the 125 | * parameters or generated for the return values. 126 | * 127 | * 128 | * 129 | * @param param1 first parameter 130 | * @param param2 param2 131 | * @param auto_param object which is not used! This documentation is added automatically! 132 | * 133 | * @retval rv return value 134 | * 135 | * @par Required fields of param1: 136 | * @arg \c test —  Description for required field param1.test 137 | * @arg \c auto_added —  auto added 138 | * @arg \c sub.auto_added —  sub.auto added 139 | * 140 | * @par Required fields of param2: 141 | * @arg \c auto_added —  auto added 142 | * 143 | * @par Required fields of auto_param: 144 | * @arg \c auto_field —  auto field 145 | * 146 | * @par Optional fields of param2: 147 | * @arg \c test2 —  Description for optional field param2.test2 148 | * 149 | * @par Generated fields of rv: 150 | * @arg \c RB —  Description for generated field rv.RB 151 | * @arg \c auto_added —  auto added 152 | * @arg \c sub.auto_added —  sub.auto added 153 | */ 154 | 155 | mlhsInnerSubst mtoc_subst_doxygen_in_namespace_m_tsbus_cotm_second_function_without_docu(matlabtypesubstitute a,matlabtypesubstitute b) { 156 | 157 | } 158 | 159 | mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_in_namespace_m_tsbus_cotm_third_function_with_sev_retvals(::othergrid auto_param) { 160 | 161 | 162 | } 163 | 164 | mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_in_namespace_m_tsbus_cotm_third_function_without_parameters() { 165 | 166 | 167 | /** \docupdate */ 168 | 169 | } 170 | 171 | }; 172 | }; 173 | -------------------------------------------------------------------------------- /src/docs/install.c: -------------------------------------------------------------------------------- 1 | /** 2 | * @page install mtoc++ installation instructions 3 | * 4 | * Make sure you have the latest version of mtoc++, see @ref download. Next step after installation is @ref tools 5 | * 6 | * @section inst_req Software requirements and recommendations 7 | * The following programs need to be available on your machine in order to use mtoc++: 8 | * - \c doxygen (>=1.8.1): mtoc++ is a filter for doxygen. If not yet available, get it at http://www.doxygen.org 9 | * 10 | * The following programs will highly improve your documentation creation experience if available: 11 | * - \c dot: A Graphviz tool that allows doxygen to create nice graphics for inheritance trees and collaboration diagrams. 12 | * - \c latex: Required to use LaTeX processing capabilities of doxygen (e.g. http://www.latex-project.org/ftp.html). 13 | * mtoc++ comes with some markups for better latex inclusion into the text flow. 14 | * Also, easy inclusion of external latex sources and styles is included in mtoc++'s tools. 15 | * - \c ghostscript: If using formulas with doxygen and you are not using pdflatex or are on a windows machine, this 16 | * is a prerequisite (see http://www.stack.nl/~dimitri/doxygen/install.html#install_bin_windows) 17 | * 18 | * If you want to build mtoc++ from source, you will also need: 19 | * - Ragel: A finite-state machine compiler. Get at http://www.complang.org/ragel 20 | * - CMake: Cross-platform make. Get at http://www.cmake.org 21 | * - dirent.h (We included a Visual Studio API implementation by Tony Ronkko for Windows) 22 | * 23 | * @section inst_binaries Using precompiled binaries 24 | * @subsection inst_binaries_win Windows users 25 | * 26 | * If you are a windows user you can directly download the binaries at @ref download. 27 | * Then simply place the binaries in a folder of your choice and add the folder to the PATH environment variable. 28 | * If you intend to use the MatlabDocMaker, you can also copy the mtoc++ binaries into the "documentation configuration files" folder 29 | * for your/each project, this path will be added to PATH by MatLab locally. 30 | * 31 | * @note Depending on your system setup, you might need to install the Microsoft Visual C++ 2010 redistributables, 32 | * which can be found here. 33 | * 34 | * @attention mtoc++ as well as doxygen expect all required programs (see \ref inst_req) to be available via the PATH environment variable, e.g. \c latex.exe or \c gswin32c.exe 35 | * must be present in order for doxygen to work with LaTeX output. Make sure that you have all requirements available, otherwise doxygen or the MatlabDocMaker will complain soon enough. 36 | * You can check/change your Windows PATH environment variable via the sequence 37 | * @code Computer \ Properties \ Advanced system settings \ Environment Variables \ Edit Path @endcode 38 | * 39 | * We are trying to always compile current Windows binaries for \c mtocpp and \c mtocpp_post and include them for direct download. 40 | * 41 | * @subsection inst_binaries_unix Unix binaries 42 | * For unix users we recommend to compile the sources following @ref inst_comp. 43 | * 44 | * However, we also plan to provide some precompiled linux binaries/packages soon. 45 | * If you find a matching choice you can use it and all you have to do is to ensure that the binaries can be found on the environment PATH. 46 | * 47 | * @section inst_comp Compiling mtoc++ from source 48 | * Please check the @ref inst_req when you intend to build mtoc++ yourself. 49 | * 50 | * mtoc++ is built using the cmake (cross-platform make) tool. This tool is available for both unix and Windows, 51 | * however, we only tested compiling our sources on linux and MS Visual Studio 2010. 52 | * 53 | * @subsection inst_comp_win Windows platforms 54 | * For Windows compilation, you need a Windows C++ compiler (e.g. MinGW or Visual Studio). Then running 55 | * the CMake GUI allows you to choose a compiler, specify any CMake configuration settings and create the 56 | * makefiles/Visual Studio projects needed for compilation. 57 | * 58 | * Furthermore, we're using the \c dirent.h library for file access. As this is a linux library we've included a file 59 | * \c dirent_msvc.h in our source, which implements the dirent api for Microsoft Visual Studio and was written by Tony Ronkko. 60 | * More information and downloads can be found at http://www.softagalleria.net/dirent.php. 61 | * 62 | * @note On Windows, you can build both 32bit and 64bit versions. If you build with Visual Studio, in recent CMake versions you need to specify the target architecture 63 | * already when choosing the generator ("Visual Studio 10 / Visual Studio 10 Win64"). This sets up the VS2010 project with the correct platforms. 64 | * In general, you can of course also use 64bit binaries from ragel and doxygen, but this is not required for successful 64bit-compilation of mtoc++ . 65 | * 66 | * @subsection inst_comp_unix Unix platforms 67 | * 68 | * The following procedure is an example of how to compile mtoc++ on a linux machine: 69 | * @code tar -xcvf mtocpp.tar.gz 70 | * cd mtocpp 71 | * 72 | * # Create build folder (optional, but more clean) 73 | * mkdir build 74 | * cd build 75 | * 76 | * # Run cmake 77 | * cmake .. 78 | * make install 79 | * @endcode 80 | * 81 | * @attention Please be aware that, depending on your installation location, you might need different access/write permissions. 82 | * For most cases, a @code sudo make install@endcode will do the job if the above snippet fails. 83 | * 84 | * @subsection inst_comp_apple Apple hints 85 | * For installation under recent Apple OS like 10.8.2, the MacPorts project is a very useful tool 86 | * to obtain prerequisites for mtoc++ compilation. Once installed, get \c ragel and \c doxygen via 87 | * @code 88 | * sudo port 89 | * > install ragel 90 | * > install doxygen 91 | * @endcode 92 | * 93 | * @subsection inst_cust CMake options: Installation folders and customization 94 | * 95 | * @note These options are explained for the linux case, for windows the CMake GUI allows to set the relevant options. 96 | * 97 | * The default value for the install prefix is \c /usr/local, so the mtocpp binaries \c mtocpp and \c mtocpp_post go to \c /usr/local/bin 98 | * and the documentation is created inside \c /usr/local/share/doc/mtocpp. 99 | * 100 | * If you want the "make install" command to copy the binaries and documentation to different locations, you can choose them by setting the following variables: 101 | * - CMAKE_INSTALL_PREFIX: Set this to whatever location you want mtoc++ to be installed. Note that the binaries are effectively copied into "CMAKE_INSTALL_PREFIX/bin" in order to comply with linux standards. 102 | * - CUSTOM_DOC_DIR: This value is "CMAKE_INSTALL_PREFIX/share/doc/mtocpp" per default. 103 | * 104 | * So typing 105 | * @code cmake -DCMAKE_INSTALL_PREFIX="/my/root/dir" -DCUSTOM_DOC_DIR="/my/docs" @endcode 106 | * will copy the binaries to \c /my/root/dir/bin and the documentation to \c /my/docs. 107 | * 108 | * If you left the \c CUSTOM_DOC_DIR flag empty the documentation would have gone to \c /my/root/dir/share/doc/mtocpp 109 | * 110 | * @section inst_test Testing 111 | * mtoc++ comes with some unit tests to check for e.g. successful compilation. 112 | * Run the tests by typing 113 | * @code make test @endcode 114 | * in the same folder where you called \c cmake. 115 | * 116 | * On Windows, dedendent on your compiler, you will either have makefiles for the test cases or a separate Visual Studio project to run the tests. 117 | * 118 | * Have fun! 119 | */ 120 | -------------------------------------------------------------------------------- /test/doxygen_in_namespace2_ref.cc: -------------------------------------------------------------------------------- 1 | namespace grid{ 2 | namespace rect{ 3 | 4 | 5 | /* (Autoinserted by mtoc++) 6 | * This source code has been filtered by the mtoc++ executable, 7 | * which generates code that can be processed by the doxygen documentation tool. 8 | * 9 | * On the other hand, it can neither be interpreted by MATLAB, nor can it be compiled with a C++ compiler. 10 | * Except for the comments, the function bodies of your M-file functions are untouched. 11 | * Consequently, the FILTER_SOURCE_FILES doxygen switch (default in our Doxyfile.template) will produce 12 | * attached source files that are highly readable by humans. 13 | * 14 | * Additionally, links in the doxygen generated documentation to the source code of functions and class members refer to 15 | * the correct locations in the source code browser. 16 | * However, the line numbers most likely do not correspond to the line numbers in the original MATLAB source files. 17 | */ 18 | 19 | mlhsInnerSubst doxygen(matlabtypesubstitute param1,matlabtypesubstitute param2,::othergrid auto_param) { 20 | 21 | 22 | /* After the first non-comment line the function body begins: */ 23 | 24 | /** Comment blocks starting with %| are interpreted as Doxygen documentation 25 | * blocks and can include doxygen commands like */ 26 | 27 | /** \todo There needs to be done something in this file */ 28 | 29 | /* fields of parameters that are used in the function body are added to the 30 | * required fileds list automatically, if they are not documentated yet. */ 31 | param1.auto_added; 32 | 33 | param2.auto_added; 34 | 35 | /* fields of return values that are assigned somewhere in the function body are 36 | * also added automatically to the list of generated fields */ 37 | rv.auto_added= 1; 38 | rv.sub.auto_added= 2; 39 | 40 | param1.sub.auto_added; 41 | 42 | auto_param.auto_field; 43 | 44 | } 45 | /** @file "test/+grid/+rect/doxygen_in_namespace.m" 46 | * @ingroup test 47 | * @brief Here comes a short description text 48 | */ 49 | /** @fn mlhsInnerSubst doxygen(matlabtypesubstitute param1,matlabtypesubstitute param2,::othergrid auto_param) 50 | * @brief Here comes a short description text 51 | * 52 | * 53 | * After the first empty documentation line, paragraphs of the detailed 54 | * description begin. 55 | * 56 | * @par Here, you have the following formatting possibilites 57 | * Adding LaTeX code in the text with \verbatim @f$ \sum_{n=0}^N \frac{1}{n} @f$ \endverbatim 58 | * @f$ \sum_{n=0}^N \frac{1}{n} @f$ or as an 59 | * equation block with @verbatim @f[ \sum_{n=0}^N \frac{1}{n}. @f] @endverbatim. 60 | * @f[ \sum_{n=0}^N \frac{1}{n}. @f] Doxygen commands 61 | * always begin with an at-character(@) OR a backslash(\\). 62 | * 63 | * Words prepended by \\c are written in a \c type-writer font. 64 | * Words prepended by \\b are written in a \b bold font. 65 | * Words prepended by \\em are written in an \em emphasized font. 66 | * 67 | * Blocks starting with @@verbatim or @@code and are ended with @@endverbatim or 68 | * @@endcode are written unformatted in a type-writer font and are not 69 | * interpreted by doxygen. 70 | * 71 | * @par Example 72 | * @verbatim 73 | /| |\ 74 | ( |-| ) 75 | ) " ( 76 | (>(Y)<) 77 | ) ( 78 | / \ 79 | ( (m|m) ) hjw 80 | ,-.),___.(,-.\`97 81 | \`---\' \`---\' 82 | @endverbatim 83 | * 84 | * @par Paragaphs starting with line ending with a double-colon 85 | * are started with a bold title line 86 | * 87 | * If, however, a double-colon at the end of a line is succeeded by: 88 | * whitespace characters, like spaces or tabulators the line is not written in a 89 | * bold font. 90 | * 91 | * @note As regularly commands like @verbatim \c @f$, @f$ @f[, @f] @endverbatim 92 | * look too distracting in matlab documentation output, the following shortcust 93 | * exist: The doxygen filter translates 94 | * - @verbatim 'word' to \c word @endverbatim resulting in the output: word, 95 | * - @verbatim `x` to @f$x@f$ @endverbatim resulting in the output: @f$x@f$ and 96 | * - @verbatim ``x`` to @f[x.@f] @endverbatim resulting in the output: @f[x@f]. 97 | * 98 | * You therefore need to be careful with the use of characters @verbatim ' ` 99 | @endverbatim. If you want to say something about the transposed of a Matrix 100 | * A, better do it in a Tex-Environment as @f$A' * B'@f$ or in a verbatim/code 101 | * environment as 102 | * @code A' * B' @endcode 103 | * 104 | * Listings can be added by prepending lines with a dash(-) 105 | * - list 1 item which can also include 106 | * newlines 107 | * - list 2 item 108 | * - and they can be nested 109 | * - subitem 2 110 | * . 111 | * - list 3 item 112 | * 113 | * and they are ended by an empty documentation line. 114 | * 115 | * Enumerations can be added by prepending lines with a dash and hash (-#) 116 | * -# first item 117 | * -# second item 118 | * -# third item 119 | * 120 | * Lines beginning with the words "Parameters" or "Return values" start a block 121 | * of argument respectively return argument descriptions. 122 | * 123 | * A line beginning with the words "Required fields of", "optional fields of" or 124 | * "generated fields of" start a block for descriptions for fields used by the 125 | * parameters or generated for the return values. 126 | * 127 | * 128 | * 129 | * @param param1 first parameter 130 | * @param auto_param object which is not used! This documentation is added automatically! 131 | * 132 | * @retval rv return value 133 | * 134 | * @par Required fields of param1: 135 | * @arg \c test —  Description for required field param1.test 136 | * 137 | * @par Required fields of param2: 138 | * 139 | * @par Required fields of auto_param: 140 | * 141 | * @par Optional fields of param2: 142 | * @arg \c test2 —  Description for optional field param2.test2 143 | * 144 | * @par Generated fields of rv: 145 | * @arg \c RB —  Description for generated field rv.RB 146 | */ 147 | 148 | mlhsInnerSubst mtoc_subst_doxygen_in_namespace_m_tsbus_cotm_second_function_without_docu(matlabtypesubstitute a,matlabtypesubstitute b) { 149 | 150 | } 151 | 152 | mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_in_namespace_m_tsbus_cotm_third_function_with_sev_retvals(::othergrid auto_param) { 153 | 154 | 155 | } 156 | /** @fn mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_in_namespace_m_tsbus_cotm_third_function_with_sev_retvals(::othergrid auto_param) 157 | * @brief a third (private) function in the test file with serveral return values 158 | * 159 | * 160 | * @param auto_param object which is not used! This documentation is added automatically! 161 | * 162 | * @retval d a return value 163 | */ 164 | 165 | mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_in_namespace_m_tsbus_cotm_third_function_without_parameters() { 166 | 167 | 168 | /** \docupdate */ 169 | 170 | } 171 | /** @fn mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_in_namespace_m_tsbus_cotm_third_function_without_parameters() 172 | * @brief a third (private) function in the test file without parameters 173 | * 174 | * 175 | * @retval d a return value 176 | */ 177 | 178 | }; 179 | }; 180 | -------------------------------------------------------------------------------- /CMakeLists.txt: -------------------------------------------------------------------------------- 1 | cmake_minimum_required(VERSION 3.0) 2 | project(MTOC++ LANGUAGES CXX VERSION 1.5) 3 | 4 | # This is the default location for docs. 5 | # Note that ${CMAKE_INSTALL_PREFIX} will be prepended automatically 6 | # unless this is set to an absolute path. 7 | if (NOT CUSTOM_DOC_DIR) 8 | set(CUSTOM_DOC_DIR "/share/doc/mtocpp" 9 | CACHE PATH "Custom directory where the documentation files will be installed") 10 | endif() 11 | 12 | set(CMAKE_CXX_FLAGS "-Wall") 13 | # path to FindRagel.cmake and WindowsToolChain.cmake 14 | list(APPEND CMAKE_MODULE_PATH ${CMAKE_SOURCE_DIR}/cmake) 15 | 16 | FIND_PACKAGE(Ragel REQUIRED) 17 | FIND_PACKAGE(Doxygen REQUIRED) 18 | FIND_PACKAGE(LATEX QUIET) 19 | 20 | IF(DOXYGEN_DOT_FOUND) 21 | SET(MTOC++_HAVE_DOT "YES") 22 | ELSE() 23 | SET(MTOC++_HAVE_DOT "NO") 24 | ENDIF() 25 | 26 | # files that need configuration... 27 | CONFIGURE_FILE( 28 | "${CMAKE_CURRENT_SOURCE_DIR}/test/test.sh.in" 29 | "${CMAKE_CURRENT_BINARY_DIR}/test.sh" 30 | @ONLY 31 | ) 32 | 33 | CONFIGURE_FILE( 34 | "${CMAKE_CURRENT_SOURCE_DIR}/src/config.h.in" 35 | "${CMAKE_CURRENT_BINARY_DIR}/config.h" 36 | ) 37 | 38 | CONFIGURE_FILE( 39 | "${CMAKE_CURRENT_SOURCE_DIR}/test/mtoc.sh.in" 40 | "${CMAKE_CURRENT_SOURCE_DIR}/test/mtoc.sh" 41 | ) 42 | 43 | CONFIGURE_FILE( 44 | "${CMAKE_CURRENT_SOURCE_DIR}/src/docs/doxygen.conf.in" 45 | "${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf" 46 | ) 47 | 48 | # pathes where to look for header files 49 | INCLUDE_DIRECTORIES("${CMAKE_CURRENT_BINARY_DIR}" "${CMAKE_CURRENT_SOURCE_DIR}/src") 50 | 51 | # Ragel preprocessing 52 | RAGEL_PARSER(src/mfilescanner_parser) 53 | RAGEL_PARSER(src/confscanner) 54 | RAGEL_PARSER(src/postprocess) 55 | 56 | # create mtocpp 57 | ADD_EXECUTABLE(mtocpp src/mtocpp.cc mfilescanner_parser.cc src/mfilescanner.cc confscanner.cc) 58 | # create mtocpp_post 59 | ADD_EXECUTABLE(mtocpp_post postprocess.cc) 60 | 61 | # add options for cross compilation on windows 62 | IF(CMAKE_CROSSCOMPILING OR MINGW) 63 | TARGET_LINK_LIBRARIES(mtocpp -lshlwapi) 64 | ENDIF() 65 | 66 | # Get current date 67 | string(TIMESTAMP CURRENT_DATE "%d-%m-%Y") 68 | 69 | # add target for HTML documentation 70 | configure_file(${CMAKE_CURRENT_SOURCE_DIR}/src/docs/mainpage.c.in ${CMAKE_CURRENT_SOURCE_DIR}/src/docs/mainpage.c) 71 | configure_file(${CMAKE_CURRENT_SOURCE_DIR}/src/docs/download_licenses.c.in ${CMAKE_CURRENT_SOURCE_DIR}/src/docs/download_licenses.c) 72 | add_custom_target(documentation_html ALL 73 | COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/doxygen.conf 74 | COMMAND mtocpp_post -q ${CMAKE_CURRENT_BINARY_DIR}/docs 75 | COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/src/docs/tabs.css ${CMAKE_CURRENT_BINARY_DIR}/docs/ 76 | DEPENDS mtocpp mtocpp_post 77 | WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/src/docs" 78 | COMMENT "Creating HTML documentation... (see ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen.log for warnings)" 79 | ) 80 | 81 | # add target for pdf documentation 82 | if(LATEX_COMPILER) 83 | add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.pdf 84 | COMMAND make 85 | COMMENT "Creating PDF documentation... (see ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.log for latex errors/warnings)" 86 | WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/latex/" 87 | ) 88 | add_custom_target(documentation_pdf ALL 89 | COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.pdf ${CMAKE_CURRENT_BINARY_DIR}/docs/manual.pdf 90 | COMMAND ${CMAKE_COMMAND} -E echo "PDF docs at ${CMAKE_CURRENT_BINARY_DIR}/docs/manual.pdf!" 91 | #COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_CURRENT_BINARY_DIR}/docs/latex 92 | DEPENDS documentation_html ${CMAKE_CURRENT_BINARY_DIR}/latex/refman.pdf 93 | ) 94 | endif() 95 | 96 | # Developer use only. Used to easily maintain the documentation website & tarballs. 97 | if (EXISTS ${WS_SRC}) 98 | find_package(Java REQUIRED) 99 | 100 | add_custom_target(create_sourcetar 101 | COMMAND ${CMAKE_COMMAND} -E tar "czf" 102 | ${WS_SRC}/mtoc++_src_${MTOC++_VERSION}.tar.gz cmake/ src/ tools/ test/ CMakeLists.txt INSTALL LICENSE 103 | WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} 104 | ) 105 | 106 | add_custom_target(create_win_binaries_packages 107 | COMMAND "${Java_JAR_EXECUTABLE}" cfM 108 | ${WS_SRC}/mtoc++_win_${MTOC++_VERSION}.zip win32/ win64/ tools/ INSTALL LICENSE 109 | COMMAND "${Java_JAR_EXECUTABLE}" cfM 110 | ${WS_SRC}/mtoc++_win_binaries_${MTOC++_VERSION}.zip win32/ win64/ INSTALL LICENSE 111 | 112 | # MatLab FEX file 113 | COMMAND "${Java_JAR_EXECUTABLE}" cfM 114 | mtoc++_fex_${MTOC++_VERSION}.zip cmake/ src/ tools/ test/ CMakeLists.txt INSTALL ${CMAKE_CURRENT_BINARY_DIR}/docs/manual.pdf 115 | WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} 116 | ) 117 | add_custom_target(create_fex_package 118 | COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_BINARY_DIR}/docs/manual.pdf . 119 | # MatLab FEX file 120 | COMMAND "${Java_JAR_EXECUTABLE}" cfM 121 | mtoc++_mlfex_${MTOC++_VERSION}.zip cmake/ src/ tools/ test/ CMakeLists.txt INSTALL manual.pdf 122 | COMMAND ${CMAKE_COMMAND} -E remove manual.pdf 123 | WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} 124 | ) 125 | add_custom_target(update_website 126 | # Copy the documentation 127 | COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_BINARY_DIR}/docs ${WS_SRC}/docs 128 | # Copy the license file 129 | COMMAND ${CMAKE_COMMAND} -E copy LICENSE ${WS_SRC}/License.txt 130 | DEPENDS create_sourcetar create_win_binaries_packages 131 | WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR} 132 | ) 133 | endif() 134 | 135 | INSTALL(TARGETS mtocpp mtocpp_post DESTINATION bin) 136 | if (EXISTS ${WS_SRC}) 137 | INSTALL(FILES ${CMAKE_CURRENT_SOURCE_DIR}/License.txt DESTINATION ${CUSTOM_DOC_DIR}) 138 | endif() 139 | #INSTALL(FILES ${CMAKE_CURRENT_SOURCE_DIR}/mtocpp.conf.example DESTINATION ${CUSTOM_DOC_DIR}) 140 | INSTALL(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/docs/ DESTINATION ${CUSTOM_DOC_DIR}) 141 | 142 | ENABLE_TESTING() 143 | # add test target: test examples (unix only so far) 144 | IF (UNIX) 145 | ADD_TEST(MTOCPP_TEST "${CMAKE_CURRENT_BINARY_DIR}/test.sh") 146 | SET_TESTS_PROPERTIES(MTOCPP_TEST PROPERTIES FAIL_REGULAR_EXPRESSION "(failed)") 147 | ENDIF() 148 | 149 | ADD_TEST(NAME MTOCPP_DOXYTEST COMMAND ${DOXYGEN_EXECUTABLE} "${CMAKE_CURRENT_SOURCE_DIR}/test/doxygen.conf") 150 | 151 | # enable dashboard scripting 152 | INCLUDE (CTest) 153 | SET (CTEST_PROJECT_NAME "MTOC++") 154 | 155 | # build a CPack driven installer package 156 | SET (CPACK_GENERATOR "DEB;TGZ") 157 | SET (CPACK_SOURCE_GENERATOR "TGZ") 158 | SET (CPACK_RESOURCE_FILE_LICENSE 159 | "${CMAKE_CURRENT_SOURCE_DIR}/LICENSE") 160 | SET (CPACK_PACKAGE_VERSION_MAJOR "${MTOC++_VERSION_MAJOR}") 161 | SET (CPACK_PACKAGE_VERSION_MINOR "${MTOC++_VERSION_MINOR}") 162 | SET (CPACK_PACKAGE_VENDOR "MDDW") 163 | SET (CPACK_PACKAGE_CONTACT "Martin Drohmann , Daniel Wirtz ") 164 | SET (CPACK_PACKAGE_DESCRIPTION_SUMMARY "Doxygen filter for Matlab M-files and scripts") 165 | SET (CPACK_PACKAGE_DESCRIPTION 166 | "This package includes two programs to build beautiful Doxygen documentation 167 | for Matlab projects. The filter program 'mtocpp' transforms relevant parts of 168 | the M-Files into C++ syntax, which can be parsed by doxygen. The generated 169 | html files can be processed by the program 'postprocess' in order to generate 170 | documentation looking more like Matlab.") 171 | SET (CPACK_DEBIAN_PACKAGE_SECTION "devel") 172 | SET (CPACK_DEBIAN_PACKAGE_SUGGESTS "doxygen") 173 | SET (CPACK_SOURCE_IGNORE_FILES "/CVS/;/\\\\.svn/;\\\\.swp$;\\\\.git/;\\\\.gitignore;build/;") 174 | INCLUDE (CPack) 175 | -------------------------------------------------------------------------------- /test/doxygen_ref.cc: -------------------------------------------------------------------------------- 1 | 2 | 3 | /* (Autoinserted by mtoc++) 4 | * This source code has been filtered by the mtoc++ executable, 5 | * which generates code that can be processed by the doxygen documentation tool. 6 | * 7 | * On the other hand, it can neither be interpreted by MATLAB, nor can it be compiled with a C++ compiler. 8 | * Except for the comments, the function bodies of your M-file functions are untouched. 9 | * Consequently, the FILTER_SOURCE_FILES doxygen switch (default in our Doxyfile.template) will produce 10 | * attached source files that are highly readable by humans. 11 | * 12 | * Additionally, links in the doxygen generated documentation to the source code of functions and class members refer to 13 | * the correct locations in the source code browser. 14 | * However, the line numbers most likely do not correspond to the line numbers in the original MATLAB source files. 15 | */ 16 | 17 | mlhsInnerSubst doxygen(::testnamespace::testclass param1,matlabtypesubstitute param2,::gridbase auto_param) { 18 | 19 | 20 | /* After the first non-comment line the function body begins: */ 21 | 22 | /** Comment blocks starting with %| are interpreted as Doxygen documentation 23 | * blocks and can include doxygen commands like */ 24 | 25 | /** \todo There needs to be done something in this file */ 26 | 27 | /* fields of parameters that are used in the function body are added to the 28 | * required fileds list automatically, if they are not documentated yet. */ 29 | param1.auto_added; 30 | 31 | 32 | 33 | /* fields of return values that are assigned somewhere in the function body are 34 | * also added automatically to the list of generated fields */ 35 | rv.auto_added= 1; 36 | rv.sub.auto_added= 2; 37 | 38 | param1.sub.auto_added; 39 | 40 | auto_param.auto_field; 41 | 42 | } 43 | /** @file "./doxygen.m" 44 | * @ingroup test 45 | * @brief Here comes a short description text 46 | */ 47 | /** @fn mlhsInnerSubst doxygen(::testnamespace::testclass param1,matlabtypesubstitute param2,::gridbase auto_param) 48 | * @brief Here comes a short description text 49 | * 50 | * 51 | * After the first empty documentation line, paragraphs of the detailed 52 | * description begin. 53 | * 54 | * @par Here, you have the following formatting possibilites 55 | * Adding LaTeX code in the text with \verbatim @f$ \sum_{n=0}^N \frac{1}{n} @f$ \endverbatim 56 | * @f$ \sum_{n=0}^N \frac{1}{n} @f$ or as an 57 | * equation block with @verbatim @f[ \sum_{n=0}^N \frac{1}{n}. @f] @endverbatim. 58 | * @f[ \sum_{n=0}^N \frac{1}{n}. @f] Doxygen commands 59 | * always begin with an at-character(@) OR a backslash(\\). 60 | * 61 | * Words prepended by \\c are written in a \c type-writer font. 62 | * Words prepended by \\b are written in a \b bold font. 63 | * Words prepended by \\em are written in an \em emphasized font. 64 | * 65 | * Chinese character: 書 66 | * 67 | * Blocks starting with @@verbatim or @@code and are ended with @@endverbatim or 68 | * @@endcode are written unformatted in a type-writer font and are not 69 | * interpreted by doxygen. 70 | * 71 | * @par Example 72 | * @verbatim 73 | /| |\ 74 | ( |-| ) 75 | ) " ( 76 | (>(Y)<) 77 | ) ( 78 | / \ 79 | ( (m|m) ) hjw 80 | ,-.),___.(,-.\`97 81 | \`---\' \`---\' 82 | @endverbatim 83 | * 84 | * @par Paragaphs starting with line ending with a double-colon 85 | * are started with a bold title line 86 | * 87 | * If, however, a double-colon at the end of a line is succeeded by: 88 | * whitespace characters, like spaces or tabulators the line is not written in a 89 | * bold font. 90 | * 91 | * @note As regularly commands like @verbatim \c @f$, @f$ @f[, @f] @endverbatim 92 | * look too distracting in matlab documentation output, the following shortcust 93 | * exist: The doxygen filter translates 94 | * - @verbatim 'word' to \c word @endverbatim resulting in the output: word, 95 | * - @verbatim `x` to @f$x@f$ @endverbatim resulting in the output: @f$x@f$ and 96 | * - @verbatim ``x`` to @f[x.@f] @endverbatim resulting in the output: @f[x@f]. 97 | * 98 | * You therefore need to be careful with the use of characters @verbatim ' ` 99 | @endverbatim. If you want to say something about the transposed of a Matrix 100 | * A, better do it in a Tex-Environment as @f$A' * B'@f$ or in a verbatim/code 101 | * environment as 102 | * @code A' * B' @endcode 103 | * 104 | * Listings can be added by prepending lines with a dash(-) 105 | * - list 1 item which can also include 106 | * newlines 107 | * - list 2 item 108 | * - and they can be nested 109 | * - subitem 2 110 | * . 111 | * - list 3 item 112 | * 113 | * and they are ended by an empty documentation line. 114 | * 115 | * Enumerations can be added by prepending lines with a dash and hash (-#) 116 | * -# first item 117 | * -# second item 118 | * -# third item 119 | * 120 | * Lines beginning with the words "Parameters" or "Return values" start a block 121 | * of argument respectively return argument descriptions. 122 | * 123 | * A line beginning with the words "Required fields of", "optional fields of" or 124 | * "generated fields of" start a block for descriptions for fields used by the 125 | * parameters or generated for the return values. 126 | * 127 | * 128 | * 129 | * @param param1 first parameter 130 | * @param param2 param2 131 | * @param auto_param object which is not used! This documentation is added automatically! 132 | * 133 | * @retval rv return value 134 | * 135 | * @par Required fields of param1: 136 | * @arg \c test —  Description for required field param1.test 137 | * @arg \c auto_added —  auto added 138 | * @arg \c sub.auto_added —  sub.auto added 139 | * 140 | * @par Required fields of auto_param: 141 | * @arg \c auto_field —  auto field 142 | * 143 | * @par Optional fields of param2: 144 | * @arg \c test2 —  Description for optional field param2.test2 145 | * 146 | * @par Generated fields of rv: 147 | * @arg \c RB —  Description for generated field rv.RB 148 | * @arg \c auto_added —  auto added 149 | * @arg \c sub.auto_added —  sub.auto added 150 | */ 151 | 152 | mlhsInnerSubst mtoc_subst_doxygen_m_tsbus_cotm_second_function_without_docu(matlabtypesubstitute a,matlabtypesubstitute b) { 153 | 154 | } 155 | 156 | mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_m_tsbus_cotm_third_function_with_sev_retvals(matlabtypesubstitute unused1,::rectgrid auto_param,matlabtypesubstitute unused2,matlabtypesubstitute unused3) { 157 | 158 | 159 | function totally_ignored_subfunction(a, b, c) 160 | /* documentation string for the totally ignored subfunction */ 161 | end 162 | 163 | body(string, with, double quote, and percent sign, " '%s'} ") /* a real comment } */ 164 | 165 | 166 | } 167 | 168 | mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_m_tsbus_cotm_third_function_without_parameters() { 169 | 170 | 171 | } 172 | 173 | noret::substitute mtoc_subst_doxygen_m_tsbus_cotm_default_parameters(::bool uml,::bool open) { 174 | 175 | 176 | } 177 | 178 | noret::substitute mtoc_subst_doxygen_m_tsbus_cotm_default_parameters2(::bool uml,::bool open) { 179 | 180 | 181 | 182 | /** \docupdate */ 183 | 184 | } 185 | 186 | /* mtoc++ warning: Optional parameter 'open' of method 'default_parameters2' has no specified default value 187 | */ -------------------------------------------------------------------------------- /test/doxygen2_ref.cc: -------------------------------------------------------------------------------- 1 | 2 | 3 | /* (Autoinserted by mtoc++) 4 | * This source code has been filtered by the mtoc++ executable, 5 | * which generates code that can be processed by the doxygen documentation tool. 6 | * 7 | * On the other hand, it can neither be interpreted by MATLAB, nor can it be compiled with a C++ compiler. 8 | * Except for the comments, the function bodies of your M-file functions are untouched. 9 | * Consequently, the FILTER_SOURCE_FILES doxygen switch (default in our Doxyfile.template) will produce 10 | * attached source files that are highly readable by humans. 11 | * 12 | * Additionally, links in the doxygen generated documentation to the source code of functions and class members refer to 13 | * the correct locations in the source code browser. 14 | * However, the line numbers most likely do not correspond to the line numbers in the original MATLAB source files. 15 | */ 16 | 17 | mlhsInnerSubst doxygen(::testnamespace::testclass param1,matlabtypesubstitute param2,::gridbase auto_param) { 18 | 19 | 20 | /* After the first non-comment line the function body begins: */ 21 | 22 | /** Comment blocks starting with %| are interpreted as Doxygen documentation 23 | * blocks and can include doxygen commands like */ 24 | 25 | /** \todo There needs to be done something in this file */ 26 | 27 | /* fields of parameters that are used in the function body are added to the 28 | * required fileds list automatically, if they are not documentated yet. */ 29 | param1.auto_added; 30 | 31 | 32 | 33 | /* fields of return values that are assigned somewhere in the function body are 34 | * also added automatically to the list of generated fields */ 35 | rv.auto_added= 1; 36 | rv.sub.auto_added= 2; 37 | 38 | param1.sub.auto_added; 39 | 40 | auto_param.auto_field; 41 | 42 | } 43 | /** @file "./doxygen.m" 44 | * @ingroup test 45 | * @brief Here comes a short description text 46 | */ 47 | /** @fn mlhsInnerSubst doxygen(::testnamespace::testclass param1,matlabtypesubstitute param2,::gridbase auto_param) 48 | * @brief Here comes a short description text 49 | * 50 | * 51 | * After the first empty documentation line, paragraphs of the detailed 52 | * description begin. 53 | * 54 | * @par Here, you have the following formatting possibilites 55 | * Adding LaTeX code in the text with \verbatim @f$ \sum_{n=0}^N \frac{1}{n} @f$ \endverbatim 56 | * @f$ \sum_{n=0}^N \frac{1}{n} @f$ or as an 57 | * equation block with @verbatim @f[ \sum_{n=0}^N \frac{1}{n}. @f] @endverbatim. 58 | * @f[ \sum_{n=0}^N \frac{1}{n}. @f] Doxygen commands 59 | * always begin with an at-character(@) OR a backslash(\\). 60 | * 61 | * Words prepended by \\c are written in a \c type-writer font. 62 | * Words prepended by \\b are written in a \b bold font. 63 | * Words prepended by \\em are written in an \em emphasized font. 64 | * 65 | * Chinese character: 書 66 | * 67 | * Blocks starting with @@verbatim or @@code and are ended with @@endverbatim or 68 | * @@endcode are written unformatted in a type-writer font and are not 69 | * interpreted by doxygen. 70 | * 71 | * @par Example 72 | * @verbatim 73 | /| |\ 74 | ( |-| ) 75 | ) " ( 76 | (>(Y)<) 77 | ) ( 78 | / \ 79 | ( (m|m) ) hjw 80 | ,-.),___.(,-.\`97 81 | \`---\' \`---\' 82 | @endverbatim 83 | * 84 | * @par Paragaphs starting with line ending with a double-colon 85 | * are started with a bold title line 86 | * 87 | * If, however, a double-colon at the end of a line is succeeded by: 88 | * whitespace characters, like spaces or tabulators the line is not written in a 89 | * bold font. 90 | * 91 | * @note As regularly commands like @verbatim \c @f$, @f$ @f[, @f] @endverbatim 92 | * look too distracting in matlab documentation output, the following shortcust 93 | * exist: The doxygen filter translates 94 | * - @verbatim 'word' to \c word @endverbatim resulting in the output: word, 95 | * - @verbatim `x` to @f$x@f$ @endverbatim resulting in the output: @f$x@f$ and 96 | * - @verbatim ``x`` to @f[x.@f] @endverbatim resulting in the output: @f[x@f]. 97 | * 98 | * You therefore need to be careful with the use of characters @verbatim ' ` 99 | @endverbatim. If you want to say something about the transposed of a Matrix 100 | * A, better do it in a Tex-Environment as @f$A' * B'@f$ or in a verbatim/code 101 | * environment as 102 | * @code A' * B' @endcode 103 | * 104 | * Listings can be added by prepending lines with a dash(-) 105 | * - list 1 item which can also include 106 | * newlines 107 | * - list 2 item 108 | * - and they can be nested 109 | * - subitem 2 110 | * . 111 | * - list 3 item 112 | * 113 | * and they are ended by an empty documentation line. 114 | * 115 | * Enumerations can be added by prepending lines with a dash and hash (-#) 116 | * -# first item 117 | * -# second item 118 | * -# third item 119 | * 120 | * Lines beginning with the words "Parameters" or "Return values" start a block 121 | * of argument respectively return argument descriptions. 122 | * 123 | * A line beginning with the words "Required fields of", "optional fields of" or 124 | * "generated fields of" start a block for descriptions for fields used by the 125 | * parameters or generated for the return values. 126 | * 127 | * 128 | * 129 | * @param param1 first parameter 130 | * @param auto_param object which is not used! This documentation is added automatically! 131 | * 132 | * @retval rv return value 133 | * 134 | * @par Required fields of param1: 135 | * @arg \c test —  Description for required field param1.test 136 | * 137 | * @par Required fields of auto_param: 138 | * 139 | * @par Optional fields of param2: 140 | * @arg \c test2 —  Description for optional field param2.test2 141 | * 142 | * @par Generated fields of rv: 143 | * @arg \c RB —  Description for generated field rv.RB 144 | */ 145 | 146 | mlhsInnerSubst mtoc_subst_doxygen_m_tsbus_cotm_second_function_without_docu(matlabtypesubstitute a,matlabtypesubstitute b) { 147 | 148 | } 149 | 150 | mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_m_tsbus_cotm_third_function_with_sev_retvals(matlabtypesubstitute unused1,::rectgrid auto_param,matlabtypesubstitute unused2,matlabtypesubstitute unused3) { 151 | 152 | 153 | function totally_ignored_subfunction(a, b, c) 154 | /* documentation string for the totally ignored subfunction */ 155 | end 156 | 157 | body(string, with, double quote, and percent sign, " '%s'} ") /* a real comment } */ 158 | 159 | 160 | } 161 | /** @fn mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_m_tsbus_cotm_third_function_with_sev_retvals(matlabtypesubstitute unused1,::rectgrid auto_param,matlabtypesubstitute unused2,matlabtypesubstitute unused3) 162 | * @brief a third (private) function in the test file with serveral return values 163 | * 164 | * 165 | * @param unused1 Marked as "~" in original m-file. 166 | * @param auto_param object which is not used! This documentation is added automatically! 167 | * @param unused2 Marked as "~" in original m-file. 168 | * @param unused3 Marked as "~" in original m-file. 169 | * 170 | * @retval d a return value 171 | */ 172 | 173 | mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_m_tsbus_cotm_third_function_without_parameters() { 174 | 175 | 176 | } 177 | /** @fn mlhsSubst ,mlhsInnerSubst ,mlhsInnerSubst ,mlhsInnerSubst > mtoc_subst_doxygen_m_tsbus_cotm_third_function_without_parameters() 178 | * @brief a third (private) function in the test file without parameters 179 | * 180 | * 181 | * @retval unused1 Marked as "~" in original m-file. 182 | * @retval d a return value 183 | * @retval unused2 Marked as "~" in original m-file. 184 | * @retval unused3 Marked as "~" in original m-file. 185 | */ 186 | 187 | noret::substitute mtoc_subst_doxygen_m_tsbus_cotm_default_parameters(::bool uml,::bool open) { 188 | 189 | 190 | } 191 | /** @fn noret::substitute mtoc_subst_doxygen_m_tsbus_cotm_default_parameters(::bool uml,::bool open) 192 | * @brief function with two default parameters 193 | * 194 | * 195 | * @param uml Set to true to create UML-like graphics output 196 | * @b Default: false 197 | * @param open Set to true if the documentation should be opened after 198 | * successful compilation 199 | * @b Default: [1;2;3] 200 | */ 201 | 202 | noret::substitute mtoc_subst_doxygen_m_tsbus_cotm_default_parameters2(::bool uml,::bool open) { 203 | 204 | 205 | 206 | /** \docupdate */ 207 | 208 | } 209 | /** @fn noret::substitute mtoc_subst_doxygen_m_tsbus_cotm_default_parameters2(::bool uml,::bool open) 210 | * @brief function with two default parameters 211 | * 212 | * 213 | * @param uml Set to true to create UML-like graphics output 214 | * @b Default: false 215 | * @param open Set to true if the documentation should be opened after 216 | * successful compilation 217 | * 218 | */ 219 | 220 | /* mtoc++ warning: Optional parameter 'open' of method 'default_parameters2' has no specified default value 221 | */ -------------------------------------------------------------------------------- /src/postprocess.rl: -------------------------------------------------------------------------------- 1 | #include "config.h" 2 | 3 | #include 4 | #include 5 | #include 6 | #include 7 | // New for directory recursion 8 | #ifdef WIN32 9 | #include 10 | #else 11 | #include 12 | #endif 13 | 14 | 15 | using std::cin; 16 | using std::cout; 17 | using std::cerr; 18 | using std::ifstream; 19 | using std::ofstream; 20 | using std::string; 21 | using std::ios_base; 22 | using std::endl; 23 | 24 | %%{ 25 | machine PostProcess; 26 | write data; 27 | 28 | # end of file character 29 | EOF = 0; 30 | 31 | # all but end of file character 32 | default = ^0; 33 | 34 | # end of line 35 | EOL = ('\r'? . '\n') @{line++;}; 36 | 37 | # matlab identifier 38 | IDENT = [A-Z\\a-z\-_][A-Z\\a-z0-9\-_]*; 39 | 40 | # matlab ifdentifier without underscore characters 41 | IDENT_WO_US = [A-Z\\a-z\-][A-Z\\a-z0-9\-]*; 42 | 43 | ANY_TAG = '<' . [^>]* . '>'; 44 | 45 | action echo { 46 | fout << fpc; 47 | if (!quiet) 48 | cout << fpc; 49 | } 50 | 51 | action st_tok { tmp_p = p; } 52 | 53 | action echo_tok { fout.write(tmp_p, p - tmp_p); 54 | if (!quiet) 55 | cout.write(tmp_p, p-tmp_p); } 56 | 57 | rettype:= |* 58 | 59 | # matlab is typeless, so discard the type 60 | ('matlabtypesubstitute' . (' '?)) => {}; 61 | 62 | # replace all "::" by "." 63 | ('::' . [A-Z\\a-z\-_]) => { fout << '.' << *(te-1); }; 64 | 65 | # a word 66 | (any - [\n <>\&\$:,\t])+ => { fout.write(ts, te-ts); }; 67 | 68 | # word separators 69 | ([\n <>\&\$:\t]) => {fout << *ts;}; 70 | 71 | # bugfix: allow '>' in the end of typenames for Daniel's generic types 72 | (('<'|'$<$') . [^&$]* . ('$>$'|'>')) => { fout.write(ts, te-ts); }; 73 | 74 | # comma or > end the type 75 | (',') => { fhold; fret; }; 76 | ('>'|'$>$') => { p -=4; fret; }; 77 | *|; 78 | 79 | # reconstruct return values 80 | retval:= |* 81 | (('<'|'$<$') . ('::')?) => { fcall rettype; }; 82 | 83 | # matlab identifier (1 return value) 84 | # ('<' . (default - [,&])*) => { cerr.write(ts+4, te - ts-4); cerr << std::endl; fout.write(ts+4, te - ts-4); }; 85 | 86 | (',' . (default - ('\&'|'\$'))*) => { 87 | if (*p == '&') 88 | fout << " "; 89 | fout.write(ts+1, te-ts-1); 90 | if (*p == '&') 91 | fout << ""; 92 | }; 93 | 94 | # end of return value 95 | ('>'|'$>$') => { 96 | if(only_retval) { fout << " ="; } 97 | fret; 98 | }; 99 | 100 | # white spaces 101 | ([ \t\n]*) => { fout.write(ts, te - ts); }; 102 | 103 | # typebreak 104 | ('
') => {}; 105 | 106 | # other tags 107 | #(ANY_TAG) => { fout.write(ts, te-ts); }; 108 | 109 | ('\\\*') => {}; 110 | 111 | *|; 112 | 113 | retvals := |* 114 | 115 | ('<' | '$<$') => {}; 116 | 117 | ('mlhs' . '\\\-'? . 'Inner' . '\\\-'? . 'Subst' . '\\\*'?) => { fcall retval; }; 118 | 119 | ('>' | '$>$') => { fout << "] ="; fgoto main; }; 120 | 121 | # white spaces and commata 122 | ([ \t\n]*) => { fout.write(ts, te - ts); }; 123 | ('
' . [ \t\n]* . ',') => { fout << ",
\n"; }; 124 | (',') => { fout << ", "; }; 125 | 126 | # other tags 127 | (ANY_TAG) => { fout.write(ts, te-ts); }; 128 | 129 | ('\\\*') => {}; 130 | 131 | *|; 132 | 133 | # function name 134 | mtocsubst:= |* 135 | ('_' | '\\_'); 136 | 137 | (IDENT_WO_US) => { fout.write(ts, te-ts); }; 138 | 139 | ('_m_tsbus_cotm_' ) => { fout << ">"; fgoto main; }; 140 | 141 | ( '\\-m\\-\\_\\-tsbus\\-\\_\\-cotm') => { fgoto main; }; 142 | *|; 143 | 144 | main:= |* 145 | # list of return values 146 | ('mlhs' . ('\\-')? . 'Subst') => { fout << "function ["; only_retval = false; fgoto retvals; }; 147 | 148 | # one return value 149 | ('mlhs' . ('\\-')? . 'Inner' . ('\\-')? . 'Subst' . ('\\\*')?) => { fout << "function "; only_retval = true; fcall retval; fout << " ="; }; 150 | 151 | # no return values 152 | ('noret::' . ('\\-')? . 'substitute' . ('\\\*')?) => {fout << "function ";}; 153 | 154 | # function name 155 | ('mtoc_subst_' | 'mtoc\\-\\_\\-subst\\-\\_\\-') => { fgoto mtocsubst; }; 156 | 157 | ('::mtoc_subst_' | ('\\-'? . '::' . '\\-' . 'mtoc\\-\\_\\-subst\\-\\_')) => { fout << '.'; fgoto mtocsubst; }; 158 | 159 | # matlab is typeless, so discard the type 160 | ('matlabtypesubstitute'. (' '?)) => {}; 161 | 162 | # remove leading "::" (global namespace identifier) 163 | ([(,>] . '::') => { fout.write(ts, 1); }; 164 | ( ('<' '$<$') . '::') => { fout.write(ts, 4); }; 165 | 166 | # replace all "::" by "." 167 | ('::' . [A-Z\\a-z\-_]) => { fout << '.' << *(te-1); }; 168 | 169 | # a word 170 | (any - [\n <>()[\]{}\&\$:.,;_\t\-])+ => { fout.write(ts, te-ts); }; 171 | 172 | (')=0') => { fout << ")"; }; 173 | 174 | # word separators 175 | ([\n <>()[\]{}\t:.;,_\&\$\-]) => {fout << *ts;}; 176 | 177 | # a single dot stays a dot 178 | ('.') => {fout << '.';}; 179 | *|; 180 | }%% 181 | 182 | class PostProcess { 183 | 184 | private: 185 | string docdir_; 186 | int line , col; 187 | char *ts , *te; 188 | int act , have; 189 | int cs; 190 | int top; 191 | int stack[5]; 192 | bool only_retval; 193 | bool quiet_; 194 | bool dry_run_; 195 | 196 | public: 197 | /** 198 | * @class PostProcess 199 | * 200 | * @change{1,2,dw,2011-11-04} Changed the postprocessor interface from taking a single file argument to 201 | * assuming the passed string to be a folder whos contents are to be postprocessed. 202 | */ 203 | // constructor 204 | PostProcess(const string &docdir, const bool quiet_flag, const bool dry_run_flag) : 205 | docdir_(docdir), 206 | line(1), 207 | ts(0), te(0), have(0), 208 | top(0), only_retval(false), 209 | quiet_(quiet_flag), 210 | dry_run_(dry_run_flag) 211 | { } 212 | 213 | int execute() 214 | { 215 | DIR *dp; 216 | if ((dp = opendir(docdir_.c_str())) == NULL) { 217 | cerr << "Error opening directory " << docdir_ << endl; 218 | return -1; 219 | } 220 | 221 | struct dirent* dirp; 222 | string file; 223 | int cnt = 0; 224 | while ((dirp = readdir(dp)) != NULL) { 225 | file = string(dirp->d_name); 226 | // Process only html files 227 | if (file.substr(file.find_last_of(".") + 1) == "tex" 228 | || file.substr(file.find_last_of(".") + 1) == "js" 229 | || (file.substr(file.find_last_of(".") + 1) == "html" && file.find("8rl") == string::npos)) { 230 | cnt += postprocess(docdir_ + string("/") + file); 231 | } 232 | } 233 | closedir(dp); 234 | return cnt; 235 | } 236 | 237 | // run postprocessor 238 | int postprocess(string file) 239 | { 240 | std::ios::sync_with_stdio(false); 241 | 242 | %% write init; 243 | 244 | ifstream is; 245 | try { 246 | is.open(file.c_str()); 247 | } catch (std::ifstream::failure e) { 248 | cerr << "Exception opening/reading file: " << file << endl; 249 | return -1; 250 | } 251 | 252 | is.seekg(0, ios_base::end); 253 | int length = is.tellg(); 254 | is.seekg(0, ios_base::beg); 255 | 256 | char* buf = new char[(int)(1.1*length)]; 257 | char* p = buf; 258 | 259 | is.read(buf, length); 260 | is.close(); 261 | 262 | ofstream fout2; 263 | if (!dry_run_) 264 | { 265 | try { 266 | fout2.open(file.c_str(), ios_base::trunc); 267 | } catch (std::ofstream::failure e) { 268 | cerr << "Exception opening/writing file:" << file << endl; 269 | return -1; 270 | } 271 | } 272 | 273 | std::ostream * fout_ptr; 274 | 275 | if (dry_run_) 276 | fout_ptr = &std::cout; 277 | else 278 | fout_ptr = &fout2; 279 | std::ostream & fout = *fout_ptr; 280 | 281 | int len = is.gcount(); 282 | char *pe = p + len; 283 | char *eof = pe; 284 | 285 | %% write exec; 286 | 287 | /* Check if we failed. */ 288 | if ( cs == PostProcess_error ) 289 | { 290 | /* Machine failed before finding a token. */ 291 | cerr << file << ": PARSE ERROR " << endl; 292 | cerr.write(p, 100); 293 | return -1; 294 | } 295 | 296 | if (!dry_run_) 297 | fout2.close(); 298 | delete buf; 299 | 300 | return 0; 301 | } 302 | }; 303 | 304 | void usage() 305 | { 306 | cout << "mtocpp_post Version " << MTOCPP_VERSION_MAJOR << "." 307 | << MTOCPP_VERSION_MINOR << endl; 308 | cout << "Usage: mtocpp_post [-q] target" << endl; 309 | cout << "\nOptions:\n -q\t\tsuppresses debug output.\n" << endl; 310 | cout << " -f\t\tsingle file argument instead of directory." << endl; 311 | } 312 | 313 | int main(int argc, char ** argv) 314 | { 315 | bool quiet = false; 316 | bool dry_run = false; 317 | bool isfile = false; 318 | string docdir; 319 | if(argc >= 2) 320 | { 321 | if (std::string("--help") == std::string(argv[1])) 322 | { 323 | usage(); 324 | return 0; 325 | } 326 | if (argc == 3 && std::string("-q") == std::string(argv[1])) 327 | { 328 | quiet = true; 329 | docdir = argv[2]; 330 | } 331 | else if (argc == 3 && std::string("-d") == std::string(argv[1])) 332 | { 333 | dry_run = true; 334 | docdir = argv[2]; 335 | } 336 | else if (argc == 3 && std::string("-f") == std::string(argv[1])) 337 | { 338 | isfile = true; 339 | docdir = argv[2]; 340 | } 341 | else if (argc == 3 && (std::string("-qf") == std::string(argv[1]) || std::string("-fq") == std::string(argv[1]))) 342 | { 343 | isfile = true; 344 | quiet = true; 345 | docdir = argv[2]; 346 | } 347 | else if(argc == 2) 348 | docdir = argv[1]; 349 | else 350 | { 351 | cerr << "wrong arguments!" << endl; 352 | usage(); 353 | exit(-2); 354 | } 355 | } 356 | else 357 | { 358 | cerr << "wrong number of arguments!" << endl; 359 | usage(); 360 | exit(-2); 361 | } 362 | 363 | if (!quiet) { 364 | if (isfile) { 365 | cout << "Running mtoc++ postprocessor on file " << docdir << endl; 366 | } else { 367 | cout << "Running mtoc++ postprocessor on directory " << docdir << endl; 368 | } 369 | } 370 | 371 | PostProcess scanner(docdir, quiet, dry_run); 372 | if (isfile) { 373 | return scanner.postprocess(docdir); 374 | } else { 375 | return scanner.execute(); 376 | } 377 | } 378 | 379 | /* vim: set et sw=2 ft=ragel: */ 380 | 381 | -------------------------------------------------------------------------------- /src/docs/+examples/Class.m: -------------------------------------------------------------------------------- 1 | classdef Class < handle 2 | % Doxygen documentation guidlines example class 3 | % 4 | % This is the documentation guideline file for class and function 5 | % documentation. KerMor uses 'doxygen' and a custom tool 'mtoc' to 6 | % create the documentation from the source files. Doxygen has specific 7 | % tags to enable easy documentation formatting/layout within the source 8 | % files. Doxygen commands always begin with an at-character(\@) OR a 9 | % backslash(\\). 10 | % 11 | % @htmlonly 12 | % Multibyte characters should work as well: 書 엄한국말 13 | % @endhtmlonly 14 | % 15 | % For a full list of commands supported by doxygen look up 16 | % http://www.stack.nl/~dimitri/doxygen/commands.html. 17 | % 18 | % @section dg_formatting mtoc++ Formatting commands 19 | % These commands are available to you within class and function 20 | % comments. 21 | % 22 | % The doxygen filter provides the following shortcuts for non-default text 23 | % content: 24 | % - @verbatim 'word' @endverbatim results in the output: 'word', 25 | % - @verbatim ` \sum_{n=0}^N \frac{1}{n} ` @endverbatim results in the 26 | % output: ` \sum_{n=0}^N \frac{1}{n} ` and 27 | % - @verbatim `` \sum_{n=0}^N \frac{1}{n} `` @endverbatim results in the 28 | % output: `` \sum_{n=0}^N \frac{1}{n} `` 29 | % 30 | % You therefore need to be careful with the use of characters @verbatim ' ` 31 | % @endverbatim If you want to say something about the transposed of a Matrix 32 | % 'A', better do it in a Tex-Environment as `A' * B'` or in a verbatim/code 33 | % environment as @code A' * B' @endcode 34 | % 35 | % @note These shortcuts are provided in mtoc as a replacement of the 36 | % default doxygen @verbatim @c @f$, @f$ @f[, @f] @endverbatim in order to 37 | % increase readability in the default matlab documentation output created 38 | % by 'doc' or 'help'. 39 | % 40 | % Paragraphs starting with a line ending with a double-colon: 41 | % are started with a bold title line 42 | % 43 | % If, however, a double-colon at the end of a line is succeeded by: 44 | % whitespace characters, like spaces or tabulators the line is not written in a 45 | % bold font. 46 | % @attention The auto-indentation command 'STRG+I' removes any 47 | % empty spaces after a line, so "Sometext: " will become "Sometext:" 48 | % and will be treated by doxygen as paragraph! 49 | % 50 | % Linking to other files and classes: 51 | % The matlab commands "See also" and "See also:" are also recognized by 52 | % mtoc++ and translated to the doxygen @@sa tag. 53 | % 54 | % @section doxygen_useful Further useful doxygen formatting shortcuts 55 | % 56 | % - Words prepended by @@b are written in a @b bold font. 57 | % - Words prepended by @@em are written in an @em emphasized font. 58 | % 59 | % Blocks starting with @@verbatim or @@code and are ended with @@endverbatim or 60 | % @@endcode are written unformatted in a type-writer font and are not 61 | % interpreted by doxygen. 62 | % 63 | % Example: 64 | % @verbatim 65 | % /| |\ 66 | % ( |-| ) 67 | % ) " ( 68 | % (>(Y)<) 69 | % ) ( 70 | % / \ 71 | % ( (m|m) ) hjw 72 | % ,-.),___.(,-.\`97 73 | % \`---\' \`---\' 74 | % @endverbatim 75 | % 76 | % Listings can be added by prepending lines with a dash(-) 77 | % - list 1 item which can also include 78 | % newlines 79 | % - list 2 item 80 | % - and they can be nested 81 | % - subitem 2 82 | % . 83 | % - list 3 item 84 | % 85 | % and they are ended by an empty documentation line. 86 | % 87 | % Enumerations can be added by prepending lines with a dash and hash (-#) 88 | % -# first item 89 | % -# second item 90 | % -# third item 91 | % 92 | 93 | properties(SetAccess=private) 94 | 95 | % Some comment on the property SomeClass. 96 | % 97 | % Properties can have specified types by use of one of the keyword 98 | % strings "of type" or "@type" in its documentation header or 99 | % documentation block. The word followed by this keyword string is 100 | % interpreted as the typename. 101 | % 102 | % The "of type" keyword only works if the 103 | % option "ENABLE_OF_TYPE_PARSING" is enabled and only in the first two 104 | % lines of the documentation block. 105 | % 106 | % @type Class 107 | % 108 | % See also: Class 109 | SomeClass = Class; 110 | end 111 | 112 | properties 113 | % Summary comment for SomeProp of type int 114 | % 115 | % Detailed comment for SomeProp. Here you can write more detailed 116 | % text for the SomeProp property. 117 | % 118 | % @default 0 @type integer 119 | SomeProp = 0; 120 | 121 | % Some row vector property. 122 | % 123 | % @type rowvec @default [1 2 3] 124 | % 125 | MyRowVec = [1 2 3]; 126 | end 127 | 128 | properties(Dependent) 129 | % Short description for a dependent property. 130 | % 131 | % Equals SomeProp times five. 132 | % 133 | % @type integer @default 0 134 | % 135 | % See also: SomeProp 136 | % @see SomeProp 137 | SomeDepProp; 138 | end 139 | 140 | methods 141 | 142 | function this = Class 143 | % This a class constructor 144 | end 145 | 146 | function set.SomeProp(this, value) 147 | % Brief setter method description 148 | % 149 | % More details on the setter 150 | this.SomeProp = value; 151 | end 152 | 153 | function v = get.SomeProp(this) 154 | % Getter brief description 155 | % 156 | % More details on the getter! 157 | v = this.SomeProp; 158 | end 159 | 160 | function v = get.SomeDepProp(this) 161 | v = this.SomeProp * 5; 162 | end 163 | 164 | function rv = example_function(this, param1, param2)%#ok 165 | % function rv = example_function(this, param1, param2) is ignored 166 | % First line: short description text for example function 167 | % 168 | % After the first empty documentation line, paragraphs of the detailed 169 | % description begin. 170 | % 171 | % Lines beginning with the words "Parameters" or "Return values" start a block 172 | % of argument respectively return argument descriptions. 173 | % 174 | % Parameters: 175 | % param1: first parameter of type double 176 | % param2: second parameter with description @type Class @default [] 177 | % 178 | % 179 | % Parameters and return values can have specified types by use of 180 | % one of the keyword strings "of type" or "@type" in its 181 | % documentation block. The word followed by this keyword string is 182 | % interpreted as the typename. 183 | % 184 | % The "of type" keyword only works if the option 185 | % "ENABLE_OF_TYPE_PARSING" is enabled and only in the first two 186 | % lines of the documentation block. 187 | % 188 | % Return values: 189 | % rv: return value @type barType 190 | % 191 | % References to other classes/members/properties can be made in 192 | % the matlab-fashion via 193 | % See also: 194 | % SomeProp noRealArguments 195 | % 196 | % or using the @@see doxygen command 197 | % @see SomeProp noRealArguments 198 | % 199 | % @note There is no technical difference as the 'See also' 200 | % keyword is simply replaced by @@see upon parsing. It is just 201 | % a convenience implementation. 202 | 203 | % After the first non-comment line the function body begins: 204 | 205 | %| After the first non-comment line, doxygen stops parsing 206 | % comments. An exception are comment blocks starting with '%%|', which 207 | % are interpreted as doxygen documentation blocks by mtoc++ and can 208 | % include doxygen commands like @@todo : 209 | 210 | %| @todo There needs to be done something in this file. (included 211 | % after main comment block) 212 | sdflkdjsf 213 | end 214 | 215 | function val1 = inputParserDemoFun(this, arg1, varargin) 216 | % This is a function demonstrating the inputParser-mtoc++ 217 | % interaction. 218 | % 219 | % Parameters: 220 | % arg1: Some number @type integer @default 1 221 | % varargin: Extra parameters. In detail 222 | % Number: Some number @type integer @default 1 223 | % Second: Some char array @type char @default 'foo' 224 | % 225 | % Return values: 226 | % val1: The result of this demo function. @type integer 227 | 228 | if nargin < 2 229 | arg1 = 1; 230 | end 231 | 232 | i = inputParser; 233 | i.addParameter('Number',1,@(v)isposintscalar(v)); 234 | i.addParameter('Second','foo',@(v)ischar(v)); 235 | res = i.parse(varargin{:}); 236 | 237 | this.SomeProp = res.Second; 238 | val1 = res.Number * arg1; 239 | end 240 | 241 | function [ret1, ret2, ret3] = many_return_args(this, arg1, arg2)%#ok 242 | % This is a base function with three left hand side arguments! 243 | % 244 | % This are function details described in the class 245 | % Class. To all three return values, one can attach type 246 | % information and documentation. 247 | % 248 | % Parameters: 249 | % arg1: A variable of type fooType. 250 | % arg2: A variable of type fooType. 251 | % 252 | % Return values: 253 | % ret1: A return value of type fooType. 254 | % ret2: A return value of type Class. 255 | % ret3: A return value with no specified type. 256 | % 257 | % 258 | % Blah. Blah. 259 | returnarg = arg1; 260 | end 261 | 262 | function returnarg = iwillbeoverridden(this, arg1, arg2)%#ok 263 | % This is a base function which will be overridden in a 264 | % subclass! 265 | % 266 | % This are function details described in the class 267 | % Class. 268 | % 269 | % Parameters: 270 | % arg1: A variable of type matrix . The type information for 271 | % this parameter is also copied to inherited classes if 272 | % @@copydoc or @@copydetails are used. 273 | % arg2: A variable of type matrix . The type information for 274 | % this parameter is also copied to inherited classes if 275 | % @@copydoc or @@copydetails are used. 276 | % 277 | % Blah. Blah. 278 | returnarg = arg1; 279 | end 280 | 281 | end 282 | 283 | methods(Sealed, Access=protected) 284 | function noRealArguments(this) 285 | % This is the function brief description. 286 | % 287 | % Here are more details on the no real arguments function. 288 | % And even some more! 289 | % 290 | % @change{0,1,dw,2011-03-22} You can even specify/log changes 291 | % on a function or property level! 292 | end 293 | end 294 | 295 | methods 296 | test1(a,b); 297 | test2(c,d); 298 | end 299 | 300 | events 301 | % This is the Test event's commentary. 302 | Test; 303 | 304 | UndocumentedEvent; 305 | end 306 | end 307 | 308 | -------------------------------------------------------------------------------- /src/dirent_msvc.h: -------------------------------------------------------------------------------- 1 | /***************************************************************************** 2 | * dirent.h - dirent API for Microsoft Visual Studio 3 | * 4 | * Copyright (C) 2006 Toni Ronkko 5 | * 6 | * Permission is hereby granted, free of charge, to any person obtaining 7 | * a copy of this software and associated documentation files (the 8 | * ``Software''), to deal in the Software without restriction, including 9 | * without limitation the rights to use, copy, modify, merge, publish, 10 | * distribute, sublicense, and/or sell copies of the Software, and to 11 | * permit persons to whom the Software is furnished to do so, subject to 12 | * the following conditions: 13 | * 14 | * The above copyright notice and this permission notice shall be included 15 | * in all copies or substantial portions of the Software. 16 | * 17 | * THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND, EXPRESS 18 | * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 19 | * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 20 | * IN NO EVENT SHALL TONI RONKKO BE LIABLE FOR ANY CLAIM, DAMAGES OR 21 | * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 22 | * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 23 | * OTHER DEALINGS IN THE SOFTWARE. 24 | * 25 | * Mar 15, 2011, Toni Ronkko 26 | * Defined FILE_ATTRIBUTE_DEVICE for MSVC 6.0. 27 | * 28 | * Aug 11, 2010, Toni Ronkko 29 | * Added d_type and d_namlen fields to dirent structure. The former is 30 | * especially useful for determining whether directory entry represents a 31 | * file or a directory. For more information, see 32 | * http://www.delorie.com/gnu/docs/glibc/libc_270.html 33 | * 34 | * Aug 11, 2010, Toni Ronkko 35 | * Improved conformance to the standards. For example, errno is now set 36 | * properly on failure and assert() is never used. Thanks to Peter Brockam 37 | * for suggestions. 38 | * 39 | * Aug 11, 2010, Toni Ronkko 40 | * Fixed a bug in rewinddir(): when using relative directory names, change 41 | * of working directory no longer causes rewinddir() to fail. 42 | * 43 | * Dec 15, 2009, John Cunningham 44 | * Added rewinddir member function 45 | * 46 | * Jan 18, 2008, Toni Ronkko 47 | * Using FindFirstFileA and WIN32_FIND_DATAA to avoid converting string 48 | * between multi-byte and unicode representations. This makes the 49 | * code simpler and also allows the code to be compiled under MingW. Thanks 50 | * to Azriel Fasten for the suggestion. 51 | * 52 | * Mar 4, 2007, Toni Ronkko 53 | * Bug fix: due to the strncpy_s() function this file only compiled in 54 | * Visual Studio 2005. Using the new string functions only when the 55 | * compiler version allows. 56 | * 57 | * Nov 2, 2006, Toni Ronkko 58 | * Major update: removed support for Watcom C, MS-DOS and Turbo C to 59 | * simplify the file, updated the code to compile cleanly on Visual 60 | * Studio 2005 with both unicode and multi-byte character strings, 61 | * removed rewinddir() as it had a bug. 62 | * 63 | * Aug 20, 2006, Toni Ronkko 64 | * Removed all remarks about MSVC 1.0, which is antiqued now. Simplified 65 | * comments by removing SGML tags. 66 | * 67 | * May 14 2002, Toni Ronkko 68 | * Embedded the function definitions directly to the header so that no 69 | * source modules need to be included in the Visual Studio project. Removed 70 | * all the dependencies to other projects so that this very header can be 71 | * used independently. 72 | * 73 | * May 28 1998, Toni Ronkko 74 | * First version. 75 | *****************************************************************************/ 76 | #ifndef DIRENT_H 77 | #define DIRENT_H 78 | 79 | #define WIN32_LEAN_AND_MEAN 80 | #include 81 | #include 82 | #include 83 | #include 84 | #include 85 | #include 86 | 87 | /* Entries missing from MSVC 6.0 */ 88 | #if !defined(FILE_ATTRIBUTE_DEVICE) 89 | # define FILE_ATTRIBUTE_DEVICE 0x40 90 | #endif 91 | 92 | /* File type and permission flags for stat() */ 93 | #if defined(_MSC_VER) && !defined(S_IREAD) 94 | # define S_IFMT _S_IFMT /* file type mask */ 95 | # define S_IFDIR _S_IFDIR /* directory */ 96 | # define S_IFCHR _S_IFCHR /* character device */ 97 | # define S_IFFIFO _S_IFFIFO /* pipe */ 98 | # define S_IFREG _S_IFREG /* regular file */ 99 | # define S_IREAD _S_IREAD /* read permission */ 100 | # define S_IWRITE _S_IWRITE /* write permission */ 101 | # define S_IEXEC _S_IEXEC /* execute permission */ 102 | #endif 103 | #define S_IFBLK 0 /* block device */ 104 | #define S_IFLNK 0 /* link */ 105 | #define S_IFSOCK 0 /* socket */ 106 | 107 | #if defined(_MSC_VER) 108 | # define S_IRUSR S_IREAD /* read, user */ 109 | # define S_IWUSR S_IWRITE /* write, user */ 110 | # define S_IXUSR 0 /* execute, user */ 111 | # define S_IRGRP 0 /* read, group */ 112 | # define S_IWGRP 0 /* write, group */ 113 | # define S_IXGRP 0 /* execute, group */ 114 | # define S_IROTH 0 /* read, others */ 115 | # define S_IWOTH 0 /* write, others */ 116 | # define S_IXOTH 0 /* execute, others */ 117 | #endif 118 | 119 | /* Indicates that d_type field is available in dirent structure */ 120 | #define _DIRENT_HAVE_D_TYPE 121 | 122 | /* File type flags for d_type */ 123 | #define DT_UNKNOWN 0 124 | #define DT_REG S_IFREG 125 | #define DT_DIR S_IFDIR 126 | #define DT_FIFO S_IFFIFO 127 | #define DT_SOCK S_IFSOCK 128 | #define DT_CHR S_IFCHR 129 | #define DT_BLK S_IFBLK 130 | 131 | /* Macros for converting between st_mode and d_type */ 132 | #define IFTODT(mode) ((mode) & S_IFMT) 133 | #define DTTOIF(type) (type) 134 | 135 | /* 136 | * File type macros. Note that block devices, sockets and links cannot be 137 | * distinguished on Windows and the macros S_ISBLK, S_ISSOCK and S_ISLNK are 138 | * only defined for compatibility. These macros should always return false 139 | * on Windows. 140 | */ 141 | #define S_ISFIFO(mode) (((mode) & S_IFMT) == S_IFFIFO) 142 | #define S_ISDIR(mode) (((mode) & S_IFMT) == S_IFDIR) 143 | #define S_ISREG(mode) (((mode) & S_IFMT) == S_IFREG) 144 | #define S_ISLNK(mode) (((mode) & S_IFMT) == S_IFLNK) 145 | #define S_ISSOCK(mode) (((mode) & S_IFMT) == S_IFSOCK) 146 | #define S_ISCHR(mode) (((mode) & S_IFMT) == S_IFCHR) 147 | #define S_ISBLK(mode) (((mode) & S_IFMT) == S_IFBLK) 148 | 149 | #ifdef __cplusplus 150 | extern "C" { 151 | #endif 152 | 153 | 154 | typedef struct dirent 155 | { 156 | char d_name[MAX_PATH + 1]; /* File name */ 157 | size_t d_namlen; /* Length of name without \0 */ 158 | int d_type; /* File type */ 159 | } dirent; 160 | 161 | 162 | typedef struct DIR 163 | { 164 | dirent curentry; /* Current directory entry */ 165 | WIN32_FIND_DATAA find_data; /* Private file data */ 166 | int cached; /* True if data is valid */ 167 | HANDLE search_handle; /* Win32 search handle */ 168 | char patt[MAX_PATH + 3]; /* Initial directory name */ 169 | } DIR; 170 | 171 | 172 | /* Forward declarations */ 173 | static DIR *opendir(const char *dirname); 174 | static struct dirent *readdir(DIR *dirp); 175 | static int closedir(DIR *dirp); 176 | static void rewinddir(DIR* dirp); 177 | 178 | 179 | /* Use the new safe string functions introduced in Visual Studio 2005 */ 180 | #if defined(_MSC_VER) && _MSC_VER >= 1400 181 | # define DIRENT_STRNCPY(dest,src,size) strncpy_s((dest),(size),(src),_TRUNCATE) 182 | #else 183 | # define DIRENT_STRNCPY(dest,src,size) strncpy((dest),(src),(size)) 184 | #endif 185 | 186 | /* Set errno variable */ 187 | #if defined(_MSC_VER) 188 | #define DIRENT_SET_ERRNO(x) _set_errno (x) 189 | #else 190 | #define DIRENT_SET_ERRNO(x) (errno = (x)) 191 | #endif 192 | 193 | 194 | /***************************************************************************** 195 | * Open directory stream DIRNAME for read and return a pointer to the 196 | * internal working area that is used to retrieve individual directory 197 | * entries. 198 | */ 199 | static DIR *opendir(const char *dirname) 200 | { 201 | DIR *dirp; 202 | 203 | /* ensure that the resulting search pattern will be a valid file name */ 204 | if (dirname == NULL) { 205 | DIRENT_SET_ERRNO (ENOENT); 206 | return NULL; 207 | } 208 | if (strlen (dirname) + 3 >= MAX_PATH) { 209 | DIRENT_SET_ERRNO (ENAMETOOLONG); 210 | return NULL; 211 | } 212 | 213 | /* construct new DIR structure */ 214 | dirp = (DIR*) malloc (sizeof (struct DIR)); 215 | if (dirp != NULL) { 216 | int error; 217 | 218 | /* 219 | * Convert relative directory name to an absolute one. This 220 | * allows rewinddir() to function correctly when the current working 221 | * directory is changed between opendir() and rewinddir(). 222 | */ 223 | if (GetFullPathNameA (dirname, MAX_PATH, dirp->patt, NULL)) { 224 | char *p; 225 | 226 | /* append the search pattern "\\*\0" to the directory name */ 227 | p = strchr (dirp->patt, '\0'); 228 | if (dirp->patt < p && *(p-1) != '\\' && *(p-1) != ':') { 229 | *p++ = '\\'; 230 | } 231 | *p++ = '*'; 232 | *p = '\0'; 233 | 234 | /* open directory stream and retrieve the first entry */ 235 | dirp->search_handle = FindFirstFileA (dirp->patt, &dirp->find_data); 236 | if (dirp->search_handle != INVALID_HANDLE_VALUE) { 237 | /* a directory entry is now waiting in memory */ 238 | dirp->cached = 1; 239 | error = 0; 240 | } else { 241 | /* search pattern is not a directory name? */ 242 | DIRENT_SET_ERRNO (ENOENT); 243 | error = 1; 244 | } 245 | } else { 246 | /* buffer too small */ 247 | DIRENT_SET_ERRNO (ENOMEM); 248 | error = 1; 249 | } 250 | 251 | if (error) { 252 | free (dirp); 253 | dirp = NULL; 254 | } 255 | } 256 | 257 | return dirp; 258 | } 259 | 260 | 261 | /***************************************************************************** 262 | * Read a directory entry, and return a pointer to a dirent structure 263 | * containing the name of the entry in d_name field. Individual directory 264 | * entries returned by this very function include regular files, 265 | * sub-directories, pseudo-directories "." and "..", but also volume labels, 266 | * hidden files and system files may be returned. 267 | */ 268 | static struct dirent *readdir(DIR *dirp) 269 | { 270 | DWORD attr; 271 | if (dirp == NULL) { 272 | /* directory stream did not open */ 273 | DIRENT_SET_ERRNO (EBADF); 274 | return NULL; 275 | } 276 | 277 | /* get next directory entry */ 278 | if (dirp->cached != 0) { 279 | /* a valid directory entry already in memory */ 280 | dirp->cached = 0; 281 | } else { 282 | /* get the next directory entry from stream */ 283 | if (dirp->search_handle == INVALID_HANDLE_VALUE) { 284 | return NULL; 285 | } 286 | if (FindNextFileA (dirp->search_handle, &dirp->find_data) == FALSE) { 287 | /* the very last entry has been processed or an error occured */ 288 | FindClose (dirp->search_handle); 289 | dirp->search_handle = INVALID_HANDLE_VALUE; 290 | return NULL; 291 | } 292 | } 293 | 294 | /* copy as a multibyte character string */ 295 | DIRENT_STRNCPY ( dirp->curentry.d_name, 296 | dirp->find_data.cFileName, 297 | sizeof(dirp->curentry.d_name) ); 298 | dirp->curentry.d_name[MAX_PATH] = '\0'; 299 | 300 | /* compute the length of name */ 301 | dirp->curentry.d_namlen = strlen (dirp->curentry.d_name); 302 | 303 | /* determine file type */ 304 | attr = dirp->find_data.dwFileAttributes; 305 | if ((attr & FILE_ATTRIBUTE_DEVICE) != 0) { 306 | dirp->curentry.d_type = DT_CHR; 307 | } else if ((attr & FILE_ATTRIBUTE_DIRECTORY) != 0) { 308 | dirp->curentry.d_type = DT_DIR; 309 | } else { 310 | dirp->curentry.d_type = DT_REG; 311 | } 312 | return &dirp->curentry; 313 | } 314 | 315 | 316 | /***************************************************************************** 317 | * Close directory stream opened by opendir() function. Close of the 318 | * directory stream invalidates the DIR structure as well as any previously 319 | * read directory entry. 320 | */ 321 | static int closedir(DIR *dirp) 322 | { 323 | if (dirp == NULL) { 324 | /* invalid directory stream */ 325 | DIRENT_SET_ERRNO (EBADF); 326 | return -1; 327 | } 328 | 329 | /* release search handle */ 330 | if (dirp->search_handle != INVALID_HANDLE_VALUE) { 331 | FindClose (dirp->search_handle); 332 | dirp->search_handle = INVALID_HANDLE_VALUE; 333 | } 334 | 335 | /* release directory structure */ 336 | free (dirp); 337 | return 0; 338 | } 339 | 340 | 341 | /***************************************************************************** 342 | * Resets the position of the directory stream to which dirp refers to the 343 | * beginning of the directory. It also causes the directory stream to refer 344 | * to the current state of the corresponding directory, as a call to opendir() 345 | * would have done. If dirp does not refer to a directory stream, the effect 346 | * is undefined. 347 | */ 348 | static void rewinddir(DIR* dirp) 349 | { 350 | if (dirp != NULL) { 351 | /* release search handle */ 352 | if (dirp->search_handle != INVALID_HANDLE_VALUE) { 353 | FindClose (dirp->search_handle); 354 | } 355 | 356 | /* open new search handle and retrieve the first entry */ 357 | dirp->search_handle = FindFirstFileA (dirp->patt, &dirp->find_data); 358 | if (dirp->search_handle != INVALID_HANDLE_VALUE) { 359 | /* a directory entry is now waiting in memory */ 360 | dirp->cached = 1; 361 | } else { 362 | /* failed to re-open directory: no directory entry in memory */ 363 | dirp->cached = 0; 364 | } 365 | } 366 | } 367 | 368 | 369 | #ifdef __cplusplus 370 | } 371 | #endif 372 | #endif /*DIRENT_H*/ 373 | -------------------------------------------------------------------------------- /src/docs/tools.c: -------------------------------------------------------------------------------- 1 | /** 2 | * @page tools Configuration and use of mtoc++ 3 | * @short Help on how to use the tools coming with mtoc++ 4 | * 5 | * Make sure you have followed the @ref install. 6 | * 7 | * @par Contents 8 | * - @ref tools_doc 9 | * - @ref tools_docmaker 10 | * - @ref tools_direct 11 | * - @ref tools_python 12 | * - @ref tools_config 13 | * - @ref config_doxy 14 | * - @ref config_mtocpp 15 | * - @ref config_latex 16 | * 17 | * @section tools_doc Documentation creation 18 | * As \c mtoc++ itself is only a filter to plug into doxygen, there is little sense in calling the binaries directly. 19 | * 20 | * Thus, mtoc++ comes with a series of tools that take over the documentation generation process for different interfaces. 21 | * 22 | * Those tools can be found inside the \c /tools folder. 23 | * 24 | * @note At some stage you will need to have access to the involved binaries like \c doxygen, \c mtocpp, \c mtocpp_post or \c latex. 25 | * It is your responsibility to ensure the availability of the binaries in whatever environment you want to create the documentation. 26 | * The most obvious way is to place all binaries inside a directory contained in your local PATH variable (both unix/windows). 27 | * We've had reported issues with MAC users, that dont have the environment set when launching MatLab from the Dock. See @ref troubleshooting for more information. 28 | * 29 | * @subsection tools_docmaker Using the MatlabDocMaker 30 | * The most convenient way of using mtoc++ within your matlab project is to use the MatlabDocMaker class coming with mtoc++. 31 | * The MatlabDocMaker is a MatLab native class that can be directly used from within MatLab in order to create the project documentation. 32 | * 33 | * Follow these simple steps in order to quickly get your first documentation: 34 | * - Place the MatlabDocMaker.m file somewhere on your project's MatLab path. 35 | * - Change the MatlabDocMaker.getProjectName method to return your project's name 36 | * - Copy the contents of the \c /tools/config folder into e.g. a subfolder of your MatLab project 37 | * - Call the MatlabDocMaker.setup method and use the folder from the previous step as your "documentation configuration files directory". 38 | * - Use the MatlabDocMaker.create method to generate your documentation and look at it in a web browser. 39 | * 40 | * See the MatlabDocMaker class description for more details on how to use it. 41 | * @note You may of course keep the MatlabDocMaker.m and the configuration files where you initially placed your mtoc++ source and point to the 42 | * appropriate directories during setup.
43 | * However, if you want to use multiple projects with mtoc++ you probably want to have different configurations for each project, so that is why we recommend to create local copies of your 44 | * tools and configuration within each project. (The MatlabDocMaker stores its setting dependent on the name you specify for the project!)
45 | * The way the MatlabDocMaker works it can be easily inserted into whatever versioning system your project uses. 46 | * As it stores important folders in MatLab preferences each developer will still have his local documentation settings (after running MatlabDocMaker.setup on each machine, of course). 47 | * 48 | * @subsection tools_direct Using mtoc++ directly 49 | * Okay, so you're a crack and want to control everything. That's fine with us! 50 | * In this case we also assume you're familiar with whatever your operating environment is and you have solid knowledge of what's going on. 51 | * First, you could simply reverse-engineer what the MatlabDocMaker is doing (it automatically generates and inserts the correct scripts read by doxygen), otherwise, here are the basic steps required to get started with mtoc++ directly. 52 | * In short, this happens by including mtoc++ as a filter for *.m files: 53 | * - Compile things as necessary and make binaries accessible 54 | * - Modify your \c doxygen configuration file: 55 | * - Setup your doxygen as usual, including the sources and output directories 56 | * - Make \c doxygen parse Matlab files 57 | * - Register mtoc++ as a filter for those files 58 | * - If you have a custom mtocpp.conf you want mtoc++ to use, you need to create a shell/batch script that passes this file to mtoc++ and use this file as filter executable 59 | * - Check if you are using latex-features of mtoc++, if so, add latex-support and provide necessary style files 60 | * - Run doxygen 61 | * - Run \c mtocpp_post passing the folder containing your HTML output as argument 62 | * - Look at some nice documentation, be happy! 63 | * - If your'e not happy, try starting with the provided Doxyfile.template in the \c tools/ directory and inserting proper values for all the placeholders we're using. 64 | * Everything related to mtoc++ has been put to the very bottom of the file, most critically: 65 | * @code 66 | * EXTENSION_MAPPING = .m=C++ 67 | * INPUT = _SourceDir_ _ConfDir_ 68 | * FILE_PATTERNS = *.m 69 | * FILTER_PATTERNS = *.m="_ConfDir_`'_FileSep_`'_MTOCFILTER_" 70 | * @endcode 71 | * Here, the underscored values need to be replaced manually in order to insert the correct values. 72 | * Essentially: 73 | * - \c EXTENSION_MAPPING tells doxygen to regard \c .m-Files as if they were \c C++ files, style-wise. 74 | * - \c INPUT tells doxygen where to look for files. 75 | * - \c FILE_PATTERNS lets doxygen also look for \c .m-Files. 76 | * - \c FILTER_PATTERNS is the most important line of the configuration. Here, you need to define scripts that should be called by doxygen before certain files are processed. 77 | * 78 | * @subsection tools_python Using the python script from a unix shell 79 | * @todo python script, yet to come 80 | * 81 | * @section tools_config Configuring mtoc++ and doxygen 82 | * 83 | * As the configuration of doxygen/mtoc++ is independent from the actual tool used we will explain it separately. 84 | * The involved files can again be found inside the \c /tools/config folder. 85 | * - \c Doxyfile.template - @ref config_doxy 86 | * - \c mtocpp.conf - @ref config_mtocpp 87 | * - \c latexextras.template - @ref config_latex 88 | * - \c class_substitutes.c - @ref config_fakeclasses 89 | * 90 | *@attention USING MTOC++ DOES NOT EXCLUDE THE REQUIREMENT TO KNOW AND UNDERSTAND DOXYGEN ITSELF!
91 | * The settings in the "Doxygen.template" file inside the \c /tools/config folder are a default 92 | * configuration for Doxygen which we thought might be useful in a MatLab setting/project and 93 | * contains some changes in order to make mtoc++ run together with doxygen. 94 | * We've had lots of feedback and problem reports which actually had to do with settings purely 95 | * regarding doxygen, so we strongly recommend having a look through @ref config_doxy and the 96 | * references therein before contacting us. Thanks! 97 | * 98 | * @subsection config_doxy Configuration options for doxygen 99 | * The \c Doxyfile.template file uses placeholders for specific folders etc. and contains any other configuration settings you want doxygen to use. 100 | * This way, the configuration files can be included into the versioning system as local developers paths are stored outside the configuration file 101 | * and are provided by the different tools coming with mtoc++. 102 | * 103 | * See http://www.stack.nl/~dimitri/doxygen/config.html for more information on doxygen configuration. 104 | * 105 | * @subsection config_mtocpp Configuration options for the mtoc++ filter 106 | * The file \c mtocpp.conf contains additional configuration for the mtoc++ parser. 107 | * 108 | * @note The mtoc++ filter takes exactly two arguments, of which the first is the file to process, and the second is an optional configuration file. 109 | * So if you dont want to customize mtoc++ because the default settings are just fine, there is nothing to do (you simply can set the filter target in doxygen to the \c mtocpp binary for the manual config case). 110 | * Otherwise, if you want to provide a config file to mtoc++, depending on your platform, you have to write a shell/batch script that 111 | * is included as filter callback in doxygen's configuration file. Inside the script, the first argument is forwarded to \c mtocpp 112 | * and the second configuration file path is provided statically in the script.
113 | * We recommend to use the MatlabDocMaker tool described in @ref tools_docmaker, as it does all that for you. 114 | * 115 | * The following is a short list of options that can be specified in the configuration file for the mtoc++ filter. 116 | * All options are declared by the syntax @code