\documentclass[a4paper]{article} %\nofiles \usepackage[T1]{fontenc} \usepackage{hyperref} \usepackage{listings} \input{lua.def} % not installed properly so just include here %% % h \parindent=0bp \textwidth=450bp \oddsidemargin=0bp % v \parskip=.5em \voffset=-70bp \textheight=750bp %%%%%%%%%%%%%%%%% \def\sectionSprout(#1,#2){\vspace{#1}\penalty#2\vspace{-#1}} \def\Sect{\sectionSprout(125bp,-150)\section} \def\SSect{\sectionSprout(100bp,-100)\subsection} \def\SSSect{\sectionSprout(80bp,-50)\subsubsection} \def\BT{\begin{tabular}} \def\ET{\end{tabular}} \def\BE{\begin{enumerate}} \def\EE{\end{enumerate}} \def\IE{\item } \def\BI{\begin{itemize}} \def\EI{\end{itemize}} \def\II{\item } \long\def\Nerd#1{{\tt #1}} \def\URL#1{{\tt #1}} \def\LuaToDoX{Lua2D\raise-.3em\hbox{O}X$_{lua}$} \def\luatodox{\Nerd{lua2dox\_lua}} \def\Doxygen{\Nerd{Doxygen}} \def\doxygen{\Nerd{doxygen}} \def\To{$\rightarrow$} \def\BS{$\backslash$} \def\Foot#1{\footnote{#1}} \lstset{language=C++ ,frame=single ,numbers=left ,numberstyle=\tiny ,tabsize=2 } \hypersetup{ pdfinfo={ Title={Lua2DoX lua ref manual} ,Subject={Autodoc tool for Lua} } ,colorlinks=true ,linkcolor=blue } \def\SetRefmanVerDate#1#2{% \def\RefmanVersion{#1}% \def\RefmanDate{#2}% } \def\SetRefmanCopyright#1{% \def\RefmanCopyright{#1}% } \SetRefmanCopyright{Copyright (c) 2012-13 Simon Dales} \SetRefmanVerDate{0.2}{7th February 2013} \begin{document} \pagestyle{empty} \begin{center} \huge \LuaToDoX \large \RefmanVersion \RefmanCopyright \RefmanDate {\fboxsep=.5em\fboxrule=.1bp\fbox{% \begin{minipage}{300bp} \hyphenpenalty=10000% \small %\begin{abstract} This is a hack to enable \doxygen{} to document lua. It uses the well-known \doxygen{} filter mechanism to allow \doxygen{} to read extra computer languages. If this works for you then enjoy. %\end{abstract} \end{minipage} }} \end{center} \tableofcontents \newpage \pagestyle{headings} \Sect{Introduction} Documenting sourcecode is a hassle. There are two basic methods of providing documented sourcecode: ``literate programming'' and ``autodoc''. Without these tools a human has to keep the documentation and code aligned, which rarely happens. \SSect{Literate Programming} If one is sufficiently organised, and it fits in with your existing work practices, then there is a lot going for literate programming. Here you write a combined document that contains both code and documentation fragments. When you want code or documentation you run it through a program which makes the appropriate files. This is theoretically the neatest way of making code because no code is generated without documentation. The best known example of literate programming is the source of \TeX. \SSect{Autodoc} In the real world we get source from many sources, usually where literate programming wasn't used or isn't available. One solution is to use an automatic documentation tool: feed it sourcecode and it will extract what documentation it can. If you feed it raw source then all it can do is tell you where it found features such as function and class declarations. If your source has been suitably prepared, then more detailed documentation can be produced. This preparation takes the form of ``magic comments''. These are source comments that contain ``magic'' features that let the autodoc tool know to make use of them. \SSSect{Doxygen} \Doxygen{} is one of the many autodoc tools use to document C-like languages. It is widely used and supported in the linux world and has Mac OS X and Windows ports. \begin{lstlisting}[firstnumber=83] void helloWorldOnce(){ printf("hello world\n"); } /*! \brief writes hello world *n This is a demo of how to loop round and print something \param N number of times round */ void helloWorldN(int N){ for (int i=0;i PROJECT_NUMBER = OUTPUT_DIRECTORY = docs SOURCE_BROWSER = yes GENERATE_LATEX = no \end{lstlisting} For example: \begin{lstlisting}[language=bash, numbers=none] PROJECT_NAME = "A Test Project" PROJECT_NUMBER = "0.1 20120926a" \end{lstlisting} Either add them to the end or find/edit the appropriate entry in \Nerd{Doxyfile}. \SSSect{run \doxygen} Once \Nerd{Doxyfile} has been edited run \doxygen{} and \LuaToDoX{} will be called as a filter. % When reading source with classes multiple passes are needed. % Each pass generates a list of member functions (as a file) that were found on this pass. % This list is read in on the next pass. % If the class+methods haven't changed this time then you only need to run it once, else run twice, % much like running \LaTeX{} \Nerd{$\backslash$tableofcontents}. \SSect{In use} As with \doxygen{} the HTML output is the most useful for development. When the project is finished then PDF output (via \LaTeX) may be useful. Typically you will have some source files open in your editor/IDE. Also keep a web-browser window open pointing at the documentation. After a bit of editing the documentation will become stale. At this point run \doxygen{} and refresh the HTML pages. \newpage \Sect{Design} \LuaToDoX{} is a \doxygen{} filter. It has a basic parser that will read each line of lua and output an equivalent in pseudo-C++. It loops round until it has found the end of the file. It only has to be good enough for \doxygen{} to see it as legal. Therefore our lua interpreter is fairly limited, but ``good enough''. The parser is relatively crude and assumes that the programmer writes lua in a fairly clean way. Some bits of lua will confuse it. In order for the source browser to work in the \doxygen{} output it must preserve the number of lines. The output of each line is either written as-is or a converted line. When \doxygen{} re-reads the source to make the source-HTML/\LaTeX{}/\ldots it uses the line number to set the position. It only supports comments that preceded the function/class declaration. Any in the middle will act as cruft in the resulting documentation. This will be slightly out of place but at least should refer to somewhere near to where it was intended. In particular ``\Nerd{\BS todo}''. This will appear in the ToDo list, but not associated with the right function. \SSect{Classes} Class declarations are assumed to be using a ``well-known'' userdefined function ``\Nerd{class()}''. It processes\goodbreak``\Nerd{TAA = class(TA)}''$_{lua}$ \To{} ``\Nerd{class TAA: public TA\{\}};''$_{C++}$. % However it will probably have some member functions. % These get converted from \goodbreak''\Nerd{A.foo(a,b)}''$_{lua}$ \To{} ``\Nerd{A::foo(a,b)}''$_{C++}$. % This is stored in a temporary file. % When \LuaToDoX{} is run a subsequent time this is used to generate a list of methods. % So \goodbreak``\Nerd{AA = class(A)}''$_{lua}$ \To{} ``\Nerd{class AA: public A\{foo(a,b);bar(x);\}};''$_{C++}$ \SSSect{Methods} Methods are mangled as: ``\Nerd{TA.fred(this,A)}''$_{lua}$ to ``\Nerd{/*! \BS memberof TA */ fred(this,A)}''$_{C++}$. This is a \doxygen{} feature introduced in 1.8.1. It allows the filter to work in a single pass. \SSect{Multiline function declarations} Because \LuaToDoX{} can only process one line at a time it cannot be guaranteed to correctly process function declarations with multiline parameter list. This is because the parser isn't sophisticated enough to guarantee finding the close paren on some random later line. So I have put in a hack that will insert the ``missing'' close paren. It looks at the function declaration that you have got and checks for a close paren. It if is not there then it will add a spoof parameter and the close. The effect is that you will get the function documented, but not with the parameter list you might expect. \begin{lstlisting}[firstnumber=94] function foo(A ,B ,C) \end{lstlisting} Becomes \begin{lstlisting}[firstnumber=94] function foo(A,___MissingCloseParenHere___) \end{lstlisting} \SSect{Multiple magic comments} The hacking of lua to C++ by \LuaToDoX{} has the limitation that some magic comments will not get associated with the correct function/class. This is a ``feature'' that might get correct in a later version. \newpage \Sect{ChangeLog} \input{ChangeLog} \end{document} %%eof