Preferred documentation style

[Port]

What style would you prefer to document TorqueScript code in? I've gathered a few examples, however feel free to post other ones.


Raw documentation

Functions 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 documentation

Similar 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 documentation

This 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 documentation

This 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)
{
   ...
}

[Ad Bot]

[Crystalwarrior]

Dokus pls.

[Lugnut]

torquedoc kinda looks prettier after processing...

eh, i dunno.

[Port]

torquedoc kinda looks prettier after processing...

What do you mean after processing?

[Greek2me]

I think TorqueDoc is the easiest to read. Here is a better example:
http://greekmods.webs.com/mods/Script_TorqueDoc/Bots.cs

This picture demonstrates what it allows for: http://forum.blockland.us/index.php?topic=242859.msg7103093#msg7103093

TomDoc also looks decent. Dokus looks to be a less structured version of TorqueDoc. It would be ok. I don't want raw to be the standard.

[Port]

I think TorqueDoc is the easiest to read. Here is a better example:
http://greekmods.webs.com/mods/Script_TorqueDoc/Bots.cs

How is it the easiest to read? If anything, the raw form is the easiest to read.

This picture demonstrates what it allows for: http://forum.blockland.us/index.php?topic=242859.msg7103093#msg7103093

You could do the same with Dokus and TomDoc, though.

[$trinick]

It entirely depends on what language I'm writing in. If I'm writing in Torque I use the "raw" style, the code should be easy enough to understand without the documentation anyway. If I'm writing C++, I always write my documentation to be compliant with Doxygen. So it looks something like this:

Code: [Select]

//!  A test class.
/*!
  A more elaborate class description.
*/
class Test
{
  public:
    //! A constructor.
    /*!
      A more elaborate description of the constructor.
    */
    Test();
    //! A destructor.
    /*!
      A more elaborate description of the destructor.
    */
   ~Test();
   
    //! A normal member taking two arguments and returning an integer value.
    /*!
      \param a an integer argument.
      \param s a constant character pointer.
      \return The test results
      \sa Test(), ~Test(), testMeToo() and publicVar()
    */
    int testMe(int a,const char *s);
       
    //! A public variable.
    /*!
      Details.
    */
    int publicVar;
};


[Treynolds416]

Raw or TorqueDoc imo

[Ipquarx]

TomDoc. It's got no silly symbols, is easy on the eyes and is easy to read, and is still well structured enough to allow for nice formatted output if one wanted to write a parser.

[Lugnut]

You could do the same with Dokus and TomDoc, though.

yeah, but no one has implemented it. if that's what you're getting at, and you're planning on implementing one, do tomdoc.

[-Jetz-]

The only place I can imagine documentation would make a big difference is the Blockland default methods. In the case of add-ons, people more often than not just read the source to figure out how to use parts of it for their own purposes, rather than working out how to call it in their own code. I think it would be best to use raw for most add-ons, then someone can find a magic lamp and ask the genie to have Badspot use TorqueDoc for the game scripts.

[Port]

yeah, but no one has implemented it.

uh

http://github.com/portify/dokus

[Aide33]

TomDoc. It's got no silly symbols, is easy on the eyes and is easy to read, and is still well structured enough to allow for nice formatted output if one wanted to write a parser.

Yeah I like this one the best also
after that it's either raw or Torquedoc

[Lugnut]

uh

http://github.com/portify/dokus

ok

[otto-san]

i don't like over-documentation so i usually go with raw style

i find it extremely hard to read code with a lot of comments all over the place