Documentation Policy

[Fireburn]

When it comes to documentation, we’ve always documentated some stuff. Some handlers are perfectly documented, other’s however are badly documented. We want to have one form of documenting in the future. Both ingame as on the trac.

There are several ways to document the gamemode. We can document both ingame and on trac. As many coders say, a good in-source documentation lessens the need for a lot of outside documentation. I would suggest we document ingame features quite a lot. New functions, new variables, checks, changes, we want everything documented, so that everyone who reads the code and knows scripting gets how it works. Document a variable by adding where it gets called, document a function and say where it gets called, document checks to say what gets checked, and what for. This will help other people in the team get the code, and will smoothen the fixing of bugs and the adding of features.

Handlers/Tips.pwn

Code:

/*******************************************************
This file handles the tips that get shown to a player at certain times.
It includes the function ShowPlayerTip, and the Tips itself.

Author: Fireburn
Date: 11-11-1111 (DD-MM-YYYY)
Version: 2.91
*******************************************************/

new aTips [SLOTS]; // This var is used to store the amount of tips a player recieved in.

/*******************************************************
ShowPlayerTip
Show's the textdraw for the player which displays the tip. The textdraw is created
from the InitTip function, which is called from OnGameModeInit. This function is called
per-player every minute, in timers.pwn.

// Author: Jay
// Date: 13th Sept
*******************************************************/
ShowPlayerTip (playerid)
{
    TextDrawShowForPlayer (playerid, Text:sometip);
}

timer.pwn

Code:

public SecondTimer(playerid)
{
    ShowPlayerTip (playerid);   // Found in handlers/tip.pwn
}

So what about the trac? We will use that to document essential things. It will function as an overview. Which file does what, which can mostly be copied from the file header, and some general lists such as a list of NPCs. We will then have a nice overview, which can help us find things in the gamemode faster.

If you have any suggestions or ideas, please react in this topic within 5 days.

[Jay]

Skeleton puppet dancing and singing

[Matthias]

Agreed, this will make the code readable after all 

[Jay]

So what about the trac? We will use that to document essential things. Where can I find what function, in what file is what located, and how do the several handlers work together. In that way the trac will work as an overview of the gamemode, which can help us find parts of the code, which will be documented inside the code.

So we have to document every function on the trac, include what file it's in, were it's called from, etc? That will waste a lot of development time. There should just be a comment above the function itself and where it's called. E.g:

Handlers/Tips.pwn

Code:

///******************************************************
// ShowPlayerTip
Show's the textdraw for the player which displays the tip. The textdraw is created
from the InitTip function, which is called from OnGameModeInit. This function is called
per-player every minute, in timers.pwn.

// Author: Jay
// Date: 13th Sept
******************************************************///
ShowPlayerTip(playerid)
{
    TextDrawShowForPlayer(playerid, Text:sometip);
}

timer.pwn

Code:

public SecondTimer()
{
    ShowPlayerTip();   // Found in handlers/tip.pwn
}

[Wesley]

I agree that that is indeed a waste of time. Most documentation should be inside the code ittself. The only things that should be on trac in my opinion is basic explanation of what directory / file does what, and possible some lists, such as a list of NPC's we have.

[Fireburn]

http://trac.sa-mp.nl/lvp/wiki/Documentation
Pre-Final version, any last suggestions, please post them here.