Doxygen filters Files

	doxyf - Doxygen filters



  Copyright (C) 2008 Walter Eaves

  qtools is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Comments are welcome.

	- Walter Eaves <Walter.Eaves@bigfoot.com>

There are a number of filters for Doxygen provided here.

qoxygen - was originally developed by Niall Ferguson and was found at
code.kx.com. It provides a filter for the q language for kdb+ system
to interwork with Doxygen.

mtoc - was originally developed by Ian Martins and provides a means of
putting MatLab scripts under Doxygen.

rtoc - is my development of mtoc and puts R scripts under Doxygen.

doxyf - is a script that can be adapted to apply filters.

emacs - Some extensions for q development in XEmacs. I've extended the
kdbp-mode.el and the q-minor-mode.el to provide an interactive
development environment. It is not currently installed by configure.

-- qoxygen.

I've now added a requirement on gnulib-tool. With it, these tools will
build for Cygwin and Solaris.

There is also a facility to build qoxygen for Windows. This uses the

 doxygen0/filters0

sub-directory.  This has a Visual Studio 2005 Solution and projects within
it. These use the output from Flex++.

There is now a dependency on Boost string functions and, because of this,
the Windows version does support the new namespace method of handling
contexts.

-- mtoc

--- From the original notes for mtoc

This is a documentation system based on Doxygen. 

You are assumed to have the following installed:

- doxygen. I use version 1.5.1. On the Mac I installed the dmg image based 
  distribution of Doyxgen and manually linked /usr/local/bin/doxygen to the 
  underlying executable that was installed. This avoids a fink or macports 
  extravaganza.

- a recent TeX installation. teTeX works well for me on Mac OSX and Linux. 
 
- lex. I use flex 2.5.35.

- a c and c++ compiler. gcc and g++ version 3 work fine.

Basics:

1. Type make in this directory. 

2. Install qoxygen to somewhere on your PATH.

3. Change to the simple_example directory and type make. 

4. simple_example/source_reference.pdf and example/source_reference/index.html
   are the pdf and html formatted output from the example.q file. See that
   q file for examples of commenting functions.

5. Same goes for benchmark_example.

6. You can copy the contents of the example directory to create your own
   projects. You should edit your copy of example/Makefile in the new project
   to point TOP_DIR to the directory containing the qoxygen executable and
   style directory. Adjust the path, also, to the included Makefile from the
   style directory. For example:

   TOP_DIR=../../tools/qoxygen
   include ../../tools/qoxygen/style/Makefile

7. "It works for me."

8. Feel free to contribute a nicer html style.

Overview:

flex converts MATLAB files into a format that is enough like C that
Doxygen can create useful documentation from it.  

Doxygen comment blocks in MATLAB begin with a "%%" string. (in c or
java it would be "/**" ).  You must enable javadoc_autobrief in the
Doxygen configuration.

comment blocks that start with "%" will be converted into regular C
block comments that start with "/*".


The Conversion:

%% changed to /**
%  changed to *  if currently in a comment block
%  changed to /* if not currently in a comment block
if a line doesn't start with "%" and its currently in a comment block,
	a "*/" is inserted at the beginning of the line to end the current
	comment block.
if a function doesn't return a value, the return type is set to "void"
if a function returns a value, the return type is set to "ret"
if a function returns multiple values, the return type is set to "rets"
all function parameters are preceded by "type"

An example input file (doxytest.m) and output file (doxytest.c) are
included that show examples of MATLAB code before and after the
translation.

files included:

readme.txt	this file
mtoc.exe	windows executable (needs cygwin)
mtoc		linux executable
lex.yy.c	source generated by flex
mtoc.l		flex script
doxytest.m	input test file
doxytest.c	output test file


To Compile:

1) install flex
2) create source from flex script
   > flex mtoc.l
3) compile
   for windows with cygwin:
       >gcc -o mtoc.exe lex.yy.c -lfl
   for linux:
       >gcc -o mtoc lex.yy.cc -lfl

To Use:

mtoc.exe infile.m outfile.c

where:
 infile.m is the input matlab file
 outfile.c is the file written with the code from the input
	file converted to a c-ish syntax.


Send questions or comments to: Ian Martins (ianxm@jhu.edu)


-- Control

[  Local Variables: ]
[  mode:text ]
[  mode:outline-minor ]
[  mode:auto-fill ]
[  fill-column: 75 ]
[  comment-column:50 ]
[  comment-start: "[  "  ]
[  comment-end:"]" ]
[  End: ]