angelscript-docgen

AngelScript Engine Interface Documentation Generator

Introduction

angelscript-docgen is a 3rdparty add on for AngelScript.

It allows you to generate the documentation for the script writers in your project. The documentation is generated as a self contained single HTML file, so it's easy to distribute. It's easy to use as it queries your AngelScript engine object for all available types and outputs it to HTML.

AngelScript version

The add-on has been tested with AngelScript 2.34 only.

Features

• Lists all registered classes and global functions automatically
• Lists all constructors and methods for all classes
• Syntax highlighting
  • Also highlights your custom types
• Visually configurable, colors, backgrounds, fonts etc. can all be tweaked if desired
• Can embed your company logo in the generated HTML file
• Has a search function built in, so script writers can quickly search for keywords
• Automatically differentiates between value object types and reference object types, and highlights them differently.

Dependencies

• The generated HTML file depends on jQuery. This is used through a CDN, so there is no need to ship it with the generated file.

License

This plugin is released under the MIT license.

How to use

• Copy the source/docgen.* files to any location in your project that you want
• Add the docgen.cpp file in your build.
• Make sure the directory where docgen.h is located is in your include paths
• Add #include "docgen.h" to your code
• Setup a ScriptDocumentationOptions object to your liking (see the source for documentation)
• Setup a DocumentationGenerator object passing it your asIScriptEngine* pointer and the options object
• Register documentation by calling the proper methods on the DocumentationGenerator object (see example below)
• Call Generate() on the DocumentationGenerator object

API Documentation

See docgen.h for documentation on the ScriptDocumentationOptions and DocumentationGenerator classes. Full documentation is available there.

Example Usage

The following is an exerpt of a modified version of scriptmgr.cpp from the example game that comes with AngelScript. The basic idea is that you register a type, and use the result value (usually r in AngelScript example code) to register the documentation for the object type, behavior, method. Then when you are done you call generate on the documentation generator to actually create the output file.

/* ...regular includes... */

#include "../../../add_on/docgen/docgen.h"

int CScriptMgr::Init()
{
    int r;

    // setup the script engine
    engine = asCreateScriptEngine();

    // setup the documentation generator
    ScriptDocumentationOptions docgenOptions;
    docgenOptions.projectName = "Example Game";
    docgenOptions.includeArrayInterface = false;      // keeps the example clean
    docgenOptions.includeStringInterface = false;     // keeps the example clean
    docgenOptions.includeWeakRefInterface = false;    // keeps the example clean
    docgenOptions.htmlSafe = false;                   // we want to be able to style ourselves with tags, e.g. <b></b>
    DocumentationGenerator docGen(engine, docgenOptions);

    /* ... continued ... */

    // Register the game object. The scripts cannot create these directly, so there is no factory function.
    r = engine->RegisterObjectType("CGameObj", 0, asOBJ_REF); assert( r >= 0 );
    r = docGen.DocumentObjectType(r, "Represents a <b>game</b> object."); assert( r >= 0 );
    r = engine->RegisterObjectBehaviour("CGameObj", asBEHAVE_ADDREF, "void f()", asMETHOD(CGameObj, AddRef), asCALL_THISCALL); assert( r >= 0 );
    r = docGen.DocumentObjectMethod(r, "Constructs a empty game object."); assert( r >= 0 );

    /* ... continued ... */

    r = engine->RegisterObjectMethod("CGameObj", "int get_x() const", asMETHOD(CGameObj, GetX), asCALL_THISCALL); assert( r >= 0 );
    r = docGen.DocumentObjectMethod(r, "Returns current horizontal position for object in-game"); assert( r >= 0 );
    r = engine->RegisterObjectMethod("CGameObj", "int get_y() const", asMETHOD(CGameObj, GetY), asCALL_THISCALL); assert( r >= 0 );
    r = docGen.DocumentObjectMethod(r, "Returns current vertical position for object in-game"); assert( r >= 0 );
    r = engine->RegisterObjectMethod("CGameObj", "bool Move(int dx, int dy)", asMETHOD(CGameObj, Move), asCALL_THISCALL); assert( r >= 0 );
    r = docGen.DocumentObjectMethod(r, "Will attempt to move the object by the given amount, returns <b>whether or not the move was legal</b>."); assert( r >= 0 );

    /* ... continued ... */

    r = docGen.Generate(); assert(r >= 0);
    return 0;
}

Removing documentation strings from the final build

By default, if nothing else is specified, the AS_GENERATE_DOCUMENTATION macro is defined as 1 in the docgen.h file. This will cause all documentation strings to be build into your executable or (shared) library, so that the documentation generator can be used. However, in the final build of your game you most likely do not want to include these strings. To disable them, define AS_GENERATE_DOCUMENTATION=0 in your build system. This causes the header to declare the generate as a stub that ignores all incoming variables, so that the compiler will optimize everything away. This way your use of this add on doesn't need to be commented out or removed, everything is handled automatically through (proper) use of the AS_GENERATE_DOCUMENTATION macro. If for some reason the compiler does not optimize the strings away, you can use the asDOC macro. This will turn strings into 0 when AS_GENERATE_DOCUMENTATION=0, so that the compiler won't even see them anymore.