TorqueDoc | Ready for use!

[Greek2me]

TorqueDoc
The TorqueScript documentation generator.

Download Script_TorqueDoc.zip

You've probably heard of programs like JavaDoc before. Here is one for TorqueScript.

It creates a web page based off of comments made on functions.

For example, this is what your code might look like:

Code: [Select]

//Documents functions in TorqueScript files and exports them to an HTML page.
//@param string mask A mask specifying one or more files. You may use the * wildcard.
//@param string title The project title, which will be displayed at the top of the navigation bar.
function document(%mask, %title)
{
%doc = new scriptGroup()
{
class = TorqueDoc;
projectTitle = (strLen(%title) ? %title : "TorqueDoc");
};
%doc.readFO = new fileObject();
%doc.add(%doc.readFO);
%doc.writeFO = new fileObject();
%doc.add(%doc.writeFO);

%doc.parse(%mask);

%functions = (%doc.numFunctions $= "" ? 0 : %doc.numFunctions);
echo("Documented" SPC %functions SPC "functions successfully.");

%doc.delete();
}

This is what the results look like.

List of Tags:

• @author - List the author of this function. Multiple @author tags should be listed in order of significance.
• @deprecated - Use the @deprecated tag to warn developers against using a function, because it may be removed in the future. This is useful when keeping old API functions for compatibility.
• @link - Include a link to a webpage.
• @param - Describe a parameter in the form "@param   varType varName   Description of the parameter."
• @private - This function is not to be called by other scripts.
• @return - Describes what the function returns in the form "@return   varType   Description of returned value."
• @see - Creates a "See Also" link to another function.

[Ad Bot]

[Subpixel]

Neat.

Can you give some example CSS so we can customize it, like what tags display which parts in the HTML?

[Lugnut]

suggestion
put it on github/bitbucket so people can hack at it and make it super lovey

have two branches, one for "plain" like the one you have, and one for "lovey" which has a bunch of unnecessary stuff like colours

[Port]

Please feel free to post any thoughts or suggestions!

Support for "themes" so I can make a much more pretty result page?

[Aide33]

Support for "themes" so I can make a much more pretty result page?

yes

[Subpixel]

Support for "themes" so I can make a much more pretty result page?

Support for CSS, really easy to put into the outcome with <style>

[Greek2me]

So the big thing is just adding CSS tags? It's been a long time since I've used it but ok I'll figure it out.

[lordician]

This is great, i always loved Javadoc, in a strange love-hate relationship.
I'll be sure to do my documentation according to these things in future bigger-ish mods/scripts.
For the smaller mods it is not so super useful, but for support scripts and the like it is hell of a good thing.

[Greek2me]

Please see the poll about private functions.

[Port]

Private functions should be explicitly labelled and warned about as well as shown in a separate list placed after the normal list of functions.

[Greek2me]

Should @param specify variable type? (since it isn't stated in the function declaration)

Also, should @return do the same?

For example, would you rather have this:

(vote yes in poll)

Code: [Select]

//Checks whether a drop-off is located between two points.
//@param point3F posA The starting point.
//@param point3F posB The ending point.
//@param float intervalFraction A cliff detection will be performed every fraction of the way between the points.
//@param float maxCliffHeight The maximum height that is not blocking.
//@param string groundType A typemask for the ground.
//@param object excludeObj An object to exclude from raycast checks.
//@return bool True if a drop-off is located between the points, otherwise false.
function Slayer_PathHandlerSG::checkCliffBlocking(%this,%posA,%posB,%intervalFraction,%maxCliffHeight,%groundType,%excludeObj)
{

}
(vote no in poll)

Code: [Select]

//Checks whether a drop-off is located between two points.
//@param posA The starting point.
//@param posB The ending point.
//@param intervalFraction A cliff detection will be performed every fraction of the way between the points.
//@param maxCliffHeight The maximum height that is not blocking.
//@param groundType A typemask for the ground.
//@param excludeObj An object to exclude from raycast checks.
//@return True if a drop-off is located between the points, otherwise false.
function Slayer_PathHandlerSG::checkCliffBlocking(%this,%posA,%posB,%intervalFraction,%maxCliffHeight,%groundType,%excludeObj)
{

}
Personally, I would say that yes they should specify variable types.

[lordician]

Since Torquescript doesn't need you to define a type for variables, i think putting this in the documentation tool is not the way to go.
You would be ignoring one of the traits of this programming language.

I vote no for the sake of recognising the trait of the language.
If people want to make sure other people know what type the variable uses in general, they can still put it in the description of the variable.

[0xBRIANSMITH]

Since Torquescript doesn't need you to define a type for variables, i think putting this in the documentation tool is not the way to go.
You would be ignoring one of the traits of this programming language.

I vote no for the sake of recognising the trait of the language.
If people want to make sure other people know what type the variable uses in general, they can still put it in the description of the variable.

I think it should still.

[Lugnut]

Since Torquescript doesn't need you to define a type for variables, i think putting this in the documentation tool is not the way to go.
You would be ignoring one of the traits of this programming language.

I vote no for the sake of recognising the trait of the language.
If people want to make sure other people know what type the variable uses in general, they can still put it in the description of the variable.

yeah, but you as a coder are expecting a certain kind of value
the point of docs is so people know how to feed the monstrous beast that is your function so it doesn't blow up

[lordician]

99% of the time you are indeed expecting a certain type yeah...
Kind of didn't think of that i guess, it is useful to see the type.