ScarDoc can be used for adding auto-documenting C++ and Lua functions. To get a function to show up in this webpage all you need to do is add a few special comments above your function. There are several different tags that you can use on your functions; some are required, while others are only optional.
When documenting Lua functions with ScarDoc you must provide type information for your functions arguments and result. This is so ScarDoc can know what types need to get passed to the functions. The tags for specifying these are @result and @args.
Example 1.1: Registering a Lua function with ScarDoc |
--? @shortdesc Set the race for a player. --? @extdesc --? The race name must be a valid race name from the attribute editor.\n\n --? This function will return false if the raceName does not exist.\n\n --? This comment will be in a new paragraph. --? @result Void --? @args PlayerID playerID, String raceName --? @refs PlayerRaces.txt, SomeOtherDoc.doc function Player_SetRace( playerID, raceName ) -- end |
Documenting C++ functions is a little more straight forward since type information is already specified in the C++ language. Since C++ type-names can look really nasty, ScarDoc converts C++ type-names to 'Designer Friendly' type-names. This way, if a Lua bound function takes a "const Math::Vector3f *" as a parameter, the person writing script does not need to worry about all this means. In this case, it would be a more friendly name such as "PositionRef." To see a list of all the types and their conversions go to >>TODO<<.
Example 1.2: Registering a C++ function with ScarDoc |
//? @shortdesc Set the race for a player. //? @extdesc //? The race name must be a valid race name from the attribute editor.\n\n //? This function will return false if the raceName does not exist.\n\n //? This comment will be in a new paragraph. //? @refs PlayerRaces.txt, SomeOtherDoc.doc static bool Player_SetRace( Player * playerID, const char * raceName ) { } |
Functions can also be categorized into named subgroups. These are the sub groups that you see in the Function list. To set the current group, use the @group tag. Once the group is set, all functions in the file below the tag will be added to this group. If another @group tag is found, this will change the current group and the functions will now get added to that group. If you do not specify a group, functions will be added to the "Various" group.
Example 1.3: Using the @group tag |
/* In this example "Group1"
will contain Function1 and Function2, "Group2" will contain
Function3 and Function4. Function0 will be added to
"Various" */
//? @shortdesc Function0 description. //? @shortdesc Function1 description. |
Tags
Following is a list of all the possible ScarDoc tags.