Generating TorqueScript documentation
by Anders Dahnielson · in Torque 3D Professional · 07/18/2014 (7:49 am) · 3 replies
I'm trying to generate the TorqueScript documentation automatically, but it feels impossible to win. I can either settle for having all script code examples being messed up and outputting all the documentation, or try to fix the examples and then not getting any module documentation generated by Doxygen.
Here's what I'm doing...
The first step is to dump the scripting documentation from the engine to a file. This is done by using the following as main.cs:
However the script code examples in the generated documentation will be messed up. That's because the engine documentation uses a custom Doxygen command. So let's try to fix it by using setting up aliases in the Doxyfile and also fix two other warnings:
So has anyone any suggestions on how to get both the module documentation and the script code examples properly generated by Doxygen?
Here's what I'm doing...
The first step is to dump the scripting documentation from the engine to a file. This is done by using the following as main.cs:
setLogMode(2);
trace(false);
dumpEngineDocs("documentation.txt");
quit();This will give us a text file containing the documentation marked up for processing by Doxygen. So the next step is to generate a configuration file for Doxygen.doxygen -gThis will produce a file named Doxyfile. If we just change the following lines in it to:
INPUT = documentation.txt GENERATE_XML = YES GENERATE_LATEX = NOAnd run doxygen:
doxygen DoxyfileIn addition to spitting out a lot of warnings and errors on stderr it will also output documentation as HTML and XML in two subdirectories respectively. In them both are filenames prefixed by "class" containing documentation of the individual classes and filenames prefixed by "group__" that contain the module documentation.
However the script code examples in the generated documentation will be messed up. That's because the engine documentation uses a custom Doxygen command. So let's try to fix it by using setting up aliases in the Doxyfile and also fix two other warnings:
ALIASES += tsxample="\verbatim" ALIASES += endtsxample="\endverbatim" ALIASES += tsexample="\verbatim" ALIASES += endtsexample="\endverbatim" ALIASES += tsexample_nopar="\verbatim" ALIASES += Return="\return" ALIASES += warn="\warning"Remove the previously generated documentation (so we can see the difference) and re-run doxygen:
rm -rf xml html doxygen DoxyfileGreat, the script code examples are now nicely included. But wait! What happened to the module documentation? Only the file for group__Decals were generated in the HTML and XML directories...
So has anyone any suggestions on how to get both the module documentation and the script code examples properly generated by Doxygen?
About the author
Bought his Torque Game Engine license in April 2004 and then pursued to not make very much with it.
#2
But the source file in that 7z archive were produced by running these two functions:
The problem is still the same: Aliasing custom command "tsexample" and friends mess upp the generation of the module documentation (grouping of classes, functions and variables).
07/18/2014 (8:52 am)
@Luis:But the source file in that 7z archive were produced by running these two functions:
function writeOutFunctions()
{
new ConsoleLogger(logger, "scriptFunctions.txt", false);
dumpConsoleFunctions();
logger.delete();
}
// Writes out declared console classes to a file.
function writeOutClasses()
{
new ConsoleLogger(logger, "scriptClasses.txt", false);
dumpConsoleClasses();
logger.delete();
}That outputs everything, stuff both defined in engine as well as in script. Not just the exported console classes, functions and variables that we get with dumpEngineDocs() (and what I'm after). Additionally, the resulting documentation does not contain any module documentation either, like we're getting with dumpEngineDocs().The problem is still the same: Aliasing custom command "tsexample" and friends mess upp the generation of the module documentation (grouping of classes, functions and variables).
Torque 3D Owner Luis Anton Rebollo