What style would you prefer to document TorqueScript code in? I've gathered a few examples, however feel free to post other ones.
Raw documentationFunctions are prefixed by successive comments containing arbitrary Markdown. This is simplest and easiest form.
// Search the Array for *item* and return it's index if found, -1 otherwise.
// This function is case-sensitive.
function Array::find(%this, %item)
{
...
}
Dokus documentationSimilar to raw documentation, Dokus documentation is a form I made for an existing TorqueScript documentation generator.
Comments before a function start with a function header, describing the return type, name and arguments.
After this, arbitrary Markdown can be written to document/describe the function.
Finally, you can optionally include special flags starting with @.
// DocumentStorage_Collection DocumentStorage::collection(string name, [bool noCreate])
// Searches for the collection *name* and returns it if found.
// If none exists and *noCreate* is not specified as true, it creates one with the name and returns it.
// With *noCreate*, -1 is returned if requesting an unexistant collection.
//
// @see DocumentStorage::isCollection
// @see DocumentStorage::deleteCollection
function DocumentStorage::collection(%this, %name, %noCreate)
{
...
}
TomDoc documentationThis style is best explained at
the official site, however here is an example regardless.
// Public: Test if a point is within a field of view.
// This uses the shape's worldbox center.
//
// point - A Point3F containing a world position to test.
// fov - The angle in degrees of the field of view (defaults to 90).
//
// Returns true if within FOV, false otherwise.
function ShapeBase::isPointWithinFOV(%this, %point, %fov)
{
...
}
TorqueDoc documentationThis is a documentation style created by Greek2me, seemingly inspired by JavaDoc. Look up JavaDoc for further details.
//Adds an objective for the bot to complete.
//@param objective An object, normally a brick, for the bot to move to.
//@param priority The importance of this objective, 0 being the lowest priority.
//@param callbackID The ID for the completion callback. The callback would be "Slayer_onBotObjectiveReached_ CALLBACKID(%mini,%bot,%objective)"
//@return bool Whether the objective was successfully added.
//@see AiConnection::removeObjective
//@see AiConnection::isObjective
//@see AiConnection::assignMiniGameObjectives
function AiConnection::addObjective(%this,%obj,%priority,%callbackID)
{
...
}
Show Posts
