documentation generation

[peterdin]

As referred to in another thread we spoke of the idea of generation documentation from the code itself.
This means : documentation is included in the code itself and is extracted using a tool.

I have done a little test using the tool doxygen http://www.doxygen.nl/ and this one seems to do the job.
I have to do some more work on customizations of that tool and report back here when I have more results available.

Perhaps someone can answer this: howfar does the scripting language follow the C/C++ syntax?

[ç i p h é r]

Perhaps someone can answer this: howfar does the scripting language follow the C/C++ syntax?

I think it's fairly close syntactically to C though there are differences, like for instance in the way strings are manipulated.

What sort of information does the tool require/are you seeking?

[peterdin]

The tool interprets the code,and extracts information from it.
You have to tell what language you use, it has no support for the script language.
But from what I've seen the syntax is really close to C/C++, so I think it'll do.

I wast just curious about the syntax, nothing special.
The trial run will show if we can get any usefull information out of it.

[ç i p h é r]

Ok. I was wondering if we could spell out the syntax it needed to pick up, but I agree, C/C++ will likely be close enough, especially for catching comments, function prototypes, and variable/constant definitions. If you can, please post a sample of the output here.

Thanks.

[peterdin]

here we go...
the following piece of documentation:

Code: Select all

#include "acr_sv_persist_i"
#include "acr_array_i"
#include "acr_tools_i"
#include "acr_debug_i"
Functions
·	void _ClearDisturbers (object oObject)
·	int _GetAreContentsLoaded (object oObject)
·	object _GetDisturber (object oObject, int nIndex)
·	int _GetIsObjectPersistantStorage (object oObject)
·	int _GetNumberOfDisturbers (object oObject)
·	int _LoadStorageObjectContents (object oObject, object oTarget=OBJECT_INVALID)
If oTarget is specified, it loads the contents into another object with an. 
·	int _PushDisturbers (object oObject, object oPC)
·	int _WriteStorageObjectContents (object oObject)
Writes the contents of oObject to the server's local persistant storage. 
·	int GetIsObjectPersistantStorage (object oObject)
Returns 1 if oObject is a persistant storage object, and 0 otherwise. 
·	object GetItemInPersistantStorage (object oObject, int nIndex)
Returns the nIndex item in oObject's persistant storage, or OBJECT_INVALID. 
·	int GetNumberOfItemsInStorage (object oObject)
Returns the number of items in this storage object, or 0 if oObject is not a persistant storage object. 
·	int GetPersistantStorageValue (object oStorage)
Returns the cumulative value of all the items in this storage. 
·	void InitializePersistantStorage ()
Initialize the persistant stoage system. 
·	void PersistantStorageOnClose (object oStorage)
Handles the OnClose event of a persistant storage object. 
·	void PersistantStorageOnDeath (object oStorage)
Handles the OnDeath event of a persistant storage object. 
·	void PersistantStorageOnDisturb (object oStorage, object oPC)
Handles the OnDisturb event of a persistant storage object. 
·	void PersistantStorageOnOpen (object oStorage)
Handles the OnOpen event of a persistant storage object. 
Variables
·	const string _ACR_PSO_DATABASE_NAME_LS = "ACR_PSO_NAME"
The local variable which contains a string which uniquely identifies a persistant storage object. 
·	const string _ACR_PSO_DISTURBED = "ACR_PSO_DISTURBED"
Local integer signifying the object was disturbed since its been opened. 
·	const int _ACR_PSO_EXPORT_DM_ONSAVE = 0
Should the DMs who disturbed the storage object's inventory be saved to the vault when the object is saved? 
·	const int _ACR_PSO_EXPORT_PC_ONSAVE = 1
Should the PCs who disturbed the storage object's inventory be saved to the vault when the object is saved? 
·	const string _ACR_PSO_NUMBER_ITEMS_VARIABLE = "NUM"
The variable name to retrieve the number of items in a storage object. 
·	const int _ACR_PSO_NUMBER_OF_BACKUPS = 3
The number of backups to maintain, in case of data loss. 
·	const string _ACR_PSO_ON_DEATH_BEHAVIOR_LI = "ACR_PSO_ONDEATH"
The local integer defining the desired behavior when the pChest is destroyed. 
·	const int _ACR_PSO_ON_DEATH_DROP_ITEMS = 1
·	const int _ACR_PSO_ON_DEATH_HIDE_ITEMS = 0
Constants representing the desired behavior of the storage if it is destroyed. 
·	const int ACR_PSO_RECORD_USERS = 5
The number of different PCs the system tracks as having accessed each persistant storage object. 

is generated from this (something ronan posted on another thread)

Code: Select all

//////////////////////////////////////////////////////////////////////////////// 
// 
//  System Name : ALFA Core Rules 
//     Filename : acr_pers_stor_i 
//      Version : 0.1 
//         Date : 5/16/06 
//       Author : Ronan 
// 
//  Local Variable Prefix = ACR_PSO 
// 
// 
//  Dependencies external of nwscript: None 
// 
//  Description 
//  This script handles all persistant storage used by PCs to store items and 
//  gold. All persistant storage should use these scripts, and none other. It 
//  also logs and evaluates the contents of persistant storage, and links 
//  to the last PCs which have used it. 
// 
//  Revision History 
//////////////////////////////////////////////////////////////////////////////// 

//////////////////////////////////////////////////////////////////////////////// 
// Includes //////////////////////////////////////////////////////////////////// 
//////////////////////////////////////////////////////////////////////////////// 

#include "acr_sv_persist_i" 
#include "acr_array_i" 
#include "acr_tools_i" 
#include "acr_debug_i" 

//////////////////////////////////////////////////////////////////////////////// 
// Constants /////////////////////////////////////////////////////////////////// 
//////////////////////////////////////////////////////////////////////////////// 

//! The number of different PCs the system tracks as having accessed each  persistant storage object. 
const int ACR_PSO_RECORD_USERS = 5; 

//! Should the PCs who disturbed the storage object's inventory be saved to the vault when the object is saved? 
const int _ACR_PSO_EXPORT_PC_ONSAVE = 1; 
//! Should the DMs who disturbed the storage object's inventory be saved to the vault when the object is saved? 
const int _ACR_PSO_EXPORT_DM_ONSAVE = 0; 

//! Constants representing the desired behavior of the storage if it is destroyed. 
const int _ACR_PSO_ON_DEATH_HIDE_ITEMS = 0; 
const int _ACR_PSO_ON_DEATH_DROP_ITEMS = 1; 

//! ADD ME!! Spawn another pStorage object on death, so what is not looted is still saved !! 

//! The number of backups to maintain, in case of data loss. 
const int  _ACR_PSO_NUMBER_OF_BACKUPS = 3; 

//! The local variable which contains a string which uniquely identifies a persistant storage object. 
const string _ACR_PSO_DATABASE_NAME_LS = "ACR_PSO_NAME"; 

//! The variable name to retrieve the number of items in a storage object. 
const string _ACR_PSO_NUMBER_ITEMS_VARIABLE = "NUM"; 

//! The local integer defining the desired behavior when the pChest is destroyed 
const string _ACR_PSO_ON_DEATH_BEHAVIOR_LI = "ACR_PSO_ONDEATH"; 

//! Local integer signifying the object was disturbed since its been opened. 
const string _ACR_PSO_DISTURBED = "ACR_PSO_DISTURBED"; 

//////////////////////////////////////////////////////////////////////////////// 
// Structures ////////////////////////////////////////////////////////////////// 
//////////////////////////////////////////////////////////////////////////////// 
struct strStorageTransactionInfo { 
    int nNetGoldToPC; 
    string sPCName; 
    string sPlayerName; 
    int nNumberOfTransactions; 
}; 

//////////////////////////////////////////////////////////////////////////////// 
/// Global Variables //////////////////////////////////////////////////////////// 
//////////////////////////////////////////////////////////////////////////////// 

//////////////////////////////////////////////////////////////////////////////// 
/// Function Prototypes ///////////////////////////////////////////////////////// 
//////////////////////////////////////////////////////////////////////////////// 


//! Initialize the persistant stoage system. 
void InitializePersistantStorage(); 

//! Handles the OnOpen event of a persistant storage object. 
void PersistantStorageOnOpen(object oStorage); 

//! Handles the OnClose event of a persistant storage object. 

/// This function saves the contents of the chest and all PCs who have disturbed 
/// its inventory. 
void PersistantStorageOnClose(object oStorage); 

//! Handles the OnDisturb event of a persistant storage object. 
void PersistantStorageOnDisturb(object oStorage, object oPC); 

//! Handles the OnDeath event of a persistant storage object. 
void PersistantStorageOnDeath(object oStorage); 

//! Returns the cumulative value of all the items in this storage. 
int GetPersistantStorageValue(object oStorage); 

//! Returns the number of items in this storage object, or 0 if oObject is not a persistant storage object. 
int GetNumberOfItemsInStorage(object oObject); 

//! Returns the nIndex item in oObject's persistant storage, or OBJECT_INVALID 

/// if oObject is not a persistant storage object, or if there is no item at 
/// nIndex. 
object GetItemInPersistantStorage(object oObject, int nIndex); 

//! Returns 1 if oObject is a persistant storage object, and 0 otherwise. 
int GetIsObjectPersistantStorage(object oObject); 

//! Loads the inventory of persistant storage object oObject. 

/// If oTarget is specified, it loads the contents into another object with an 

/// inventory. Whatever the target, the inventory of it is DESTROYED, and 
/// replaced with the objects stored in the database. 
/// Returns the number of items loaded. 
///
int _LoadStorageObjectContents(object oObject, object oTarget = OBJECT_INVALID); 

//! Writes the contents of oObject to the server's local persistant storage. 

/// It checks for errors as it goes, and if an error is detected, the entire 
/// write is aborted, and the storage object reverts to the old version. 
int _WriteStorageObjectContents(object oObject); 

// Return's 1 if oObject's storage contents have been loaded, or 0 if not. 
// Also returns 0 if oObject is not a persistant storage object. 
int _GetAreContentsLoaded(object oObject); 

// Returns the number of PCs who have disturbed oObject's inventory since the 
// last time it was closed. 
int _GetNumberOfDisturbers(object oObject); 

// Adds a PC or DM to the list of characters who have disturbed this object's 
// inventory since the last time it was closed. 
int _PushDisturbers(object oObject, object oPC); 

// Clears the list of PCs who have disturbed this storage object's inventory. 
// Generally called OnClose. 
void _ClearDisturbers(object oObject); 

// Returns oObject's nIndex disturber, or OBJECT_INVALID on an error. 
object _GetDisturber(object oObject, int nIndex); 

//////////////////////////////////////////////////////////////////////////////// 
// Function Definitions //////////////////////////////////////////////////////// 
//////////////////////////////////////////////////////////////////////////////// 

void InitializePersistantStorage() { 
    _persistantStorageDebugId = CreateDebugSystem("Persistant storage: ", DEBUG_TARGET_NONE, DEBUG_TARGET_LOG, DEBUG_TARGET_LOG); 
} 

int _GetIsObjectPersistantStorage(object oObject) { 
    return GetLocalString(oObject, _ACR_PSO_DATABASE_NAME_LS) != ""; 
} 

int _LoadStorageObjectContents(object oObject, object oTarget = OBJECT_INVALID) { 
} 

void PersistantStorageOnOpen(object oStorage) { 
    if(!_GetAreContentsLoaded(oStorage)) { 
        _LoadStorageObjectContents(oStorage); 
    } 
} 

void PersistantStorageOnClose(object oStorage) { 

    // If the chest's contents haven't been altered, we do nothing. 
    if(!GetLocalInt(oStorage, _ACR_PSO_DISTURBED)) { 
        return; 
    } 

    // Find every exportable character who has disturbed this object, and export 
    // them. 
    int nDisturbers = _GetNumberOfDisturbers(); 
    int i; 
    for(i=0; i<nDisturbers; i++) { 
        object oPC = _GetDisturber(oObject, nDisturbers); 
        ExportSingleCharacter(oPC); 
        // Update oStorage's list of transactions?!? 
    } 
    _WriteStorageObjectContents(oStorage); 
} 

void PersistantStorageOnDisturb(object oStorage, object oPC) { 
    _PushDisturbers(oStorage, oDisturber); 
    // Record the transaction?!? 
    SetLocalInt(oStorage, _ACR_PSO_DISTURBED, 1); 
} 

void PersistantStorageOnDeath(object oStorage) { 
// ADD ME!! Spawn another pStorage object on death, so what is not looted is 
// still saved at reset !! 
    int nOnDeath = GetLocalInt(oStorage, _ACR_PSO_ON_DEATH_BEHAVIOR_LI); 
    if(nOnDeath == _ACR_PSO_ON_DEATH_HIDE_ITEMS) { 
        DestroyInventory(oStorage); 
    } else if(nOnDeath == _ACR_PSO_ON_DEATH_DROP_ITEMS) { 
        if(!_GetAreContentsLoaded(oStorage)) { 
            _LoadStorageObjectContents(oStorage); 
        } 
    } 
}

I had to make changes to the comment style in order to get the documentation out. There's probably a way to configure the tool such that understans alfa style comments, but I haven't found that yet .
furthermore: please be aware that this is text representation. The same information in html and browesable would be much more easy to use.
Also I left the detailed descriptions out of the documentation because the post will become to big.
My feeling is that this gives at least an idea of the possibilities.
for an example of a real life prodcut check out http://icu.sourceforge.net/apiref/icu4c/

more to follow...

[ç i p h é r]

If you can get it anywhere close to the sample, I'd be very impressed.

[ç i p h é r]

Any progress on this front?

[peterdin]

not much:(
RL is keeping me very busy.
It's still on the planning though.

[peterdin]

Have a look at:
edit: link removed

it is only the omega wand files processed. No changes made to the code.

[ç i p h é r]

Hmmm...the main section is blank. What's supposed to be there? A summary? The file contents are good, but I don't see any comments. Is it not picking those up or are there no comments in the files?

Is this still a work in progress? It's nice to have as a data dictionary if nothing else, but I hope we can snag comments as well that explain what the functions do and the variables store.

Thanks peterdin.

[peterdin]

I just ran the tool, no changes done.
If we want to take up comments something has to be done (probably) on the code (comment style)
I'll figure out what

[ç i p h é r]

I wonder if it's looking for comments on the function definitions rather than the prototypes, which is where we're putting them (for the toolset).

[peterdin]

it needs a certain structure for the comments.
like this:
//! Convert a base item type to a string

//!
//!uses a switch to convert

string GetBaseItemTypeAsString(int type) {

I've uploaded the result of this. check out this function. (also the BGR struct)

furthermore I don't think it matters if you comment the prototype or the function. If you run the tool on the prototypes it should work.
I'll try that.
edit:
find the results at
edit: link removed. send me a PM if you need it.
I just changed all the "//" with "//!" (of the wealth and the spells include) if you want to go through with this, the comment style must be adapted.

[ç i p h é r]

It's definitely better. I'm quite surprised that it doesn't catch // as a comment prefix. That's pretty standard, unless //! is a way to explicitly control what the parser catches and ignores...can't see what we'd want ignored though.

Anyway, good stuff. I'd definitely like to use this. Ronan, do you have any opinions? You've done a lot of the architectural work so far and that would need to be updated. I can update on my end as well, but we'd best do this sooner rather than later to avoid a larger rework project.

[peterdin]

it parses the special comments.(as far as I can see from the documentation this cannot be changed)
So the comments needs to be changed
We need it to be changed like this

//! This is the brief comment for greatfunctionA
this empty line is necessary
//! The extended comment for greatfuncA
//! is just this. As you can see from the name it is a great function and
//! performs blah blah blah blah some more BS
void greatfunctionaA(void)
{
}

this will show up in the overview as:
This is the brief comment for greatfunctionA
and in the details
This is the brief comment for greatfunctionA
is just this. As you can see from the name it is a great function and
performs blah blah blah blah some more BS