* Random documentation of database files.

git-svn-id: https://rathena.svn.sourceforge.net/svnroot/rathena/trunk@14986 54d463be-8e91-2dee-dedb-b68131a5f0ec

11 files changed, 132 insertions, 16 deletions

diff --git a/Changelog-Trunk.txt b/Changelog-Trunk.txt
index 1363e4119..eabc37140 100644
--- a/Changelog-Trunk.txt
+++ b/Changelog-Trunk.txt
@@ -1,6 +1,7 @@
 Date	Added
 
 2011/10/28
+	* Random documentation of database files. [Ai4rei]
 	* Fixed db/packet_db.txt reading not checking for max. amount of positions. [Ai4rei]
 	* Introduced MAX_GUILD_SKILL_REQUIRE to fix inconsistency in amount of prereq. guild skills.
 2011/10/26
diff --git a/db/abra_db.txt b/db/abra_db.txt
index ae7f59e11..c25621f91 100644
--- a/db/abra_db.txt
+++ b/db/abra_db.txt
@@ -1,7 +1,16 @@
-// Hocus-Pocus Castable Skills Database
+// Hocus-Pocus (Abrakadabra) Castable Skills Database
 //
 // Structure of Database:
 // SkillID,DummyName,RequiredHocusPocusLevel,Rate
+//
+// 01. SkillID                  Skill ID to be casted by hocus pocus.
+// 02. DummyName                Name of the skill (informative, not used by server).
+// 03. RequiredHocusPocusLevel  Minimum skill level of hocus pocus for the current skill to be selected.
+// 04. Rate                     Chance at which the skill is selected (1 = 0.01%, 10000 = 100%).
+//
+// NOTE: The skill is picked at random from the entire database and then tested for rate. If it
+//       does not succeed at that rate, an another skill is picked and tested. This continues
+//       until a skill succeeds.
 
 //1,Basic Skill,1,0
 
diff --git a/db/castle_db.txt b/db/castle_db.txt
index 050cfc280..37d615496 100644
--- a/db/castle_db.txt
+++ b/db/castle_db.txt
@@ -1,7 +1,15 @@
 // Guild Castles Database
 //
 // Structure of Database:
-// CastleID,MapName,CastleName,OnGuildBreakEventName(to abandon captured castles),Flag(reserved)
+// CastleID,MapName,CastleName,OnGuildBreakEventName,Flag
+//
+// 01. CastleID                 Unique ID of the castle.
+// 02. MapName                  Map name to be considered as the castle map.
+// 03. CastleName               Name of the castle (used by scripts and guardian name tags).
+// 04. OnGuildBreakEventName    NPC unique name to invoke ::OnGuildBreak on, when a occupied
+//                              castle is abandoned during guild break.
+// 05. Flag                     Switch flag (reserved as of athena-dev mod0796~0801, not used by server).
+
 0,aldeg_cas01,Neuschwanstein,Agit#aldeg_cas01,1		// kRO : Noisyubantian
 1,aldeg_cas02,Hohenschwangau,Agit#aldeg_cas02,1		// kRO : Hohensyubangawoo
 2,aldeg_cas03,Nuenberg,Agit#aldeg_cas03,1			// kRO : Nyirenverk
diff --git a/db/const.txt b/db/const.txt
index 4d4cb3e69..6cb94f85e 100644
--- a/db/const.txt
+++ b/db/const.txt
@@ -1,3 +1,19 @@
+// Script Constant Database
+//
+// Structure of Database:
+// Identifier	Value[	Type]
+//
+// Alternatively:
+// Identifier,Value[,Type]
+//
+// 01. Identifier   Unique name for the constant, must not have same name as script commands, functions or variables.
+// 02. Value        Value assigned to the constant. This value cannot be changed during the runtime of the server.
+// 03. Type         Specifies whether the identifier is a constant (0) or a parameter (1) (optional, defaults to 0).
+//
+// NOTE:            Parameters are special in that they retrieve certain runtime values depending on the specified ID
+//                  in field Value. Depending on the implementation values assigned by scripts to parameters will affect
+//                  runtime values, such as Zeny, as well (see pc_readparam/pc_setparam).
+
 Job_Novice	0
 Job_Swordman	1
 Job_Mage	2
diff --git a/db/create_arrow_db.txt b/db/create_arrow_db.txt
index b5f80a215..f438e7de1 100644
--- a/db/create_arrow_db.txt
+++ b/db/create_arrow_db.txt
@@ -2,6 +2,13 @@
 //
 // Structure of Database:
 // SourceID,MakeID1,MakeAmount1,...,MakeID5,MakeAmount5
+//
+// 01. SourceID     ID of the item, that is consumed by Arrow Crafting.
+// 02. MakeID       ID of the item received from Arrow Crafting.
+// 03. MakeAmount   Amount of MakeID item received from Arrow Crafting.
+// ...
+//
+// NOTE: Up to MAX_ARROW_RESOURCE (typically 5) ID/Amount pairs can be specified.
 
 // Old Blue Box --> 50 Sharp Arrows, 50 Sleep Arrows
 603,1764,50,1768,50
diff --git a/db/guild_skill_tree.txt b/db/guild_skill_tree.txt
index 2ae734f70..8572244aa 100644
--- a/db/guild_skill_tree.txt
+++ b/db/guild_skill_tree.txt
@@ -1,4 +1,16 @@
-//Skill-ID,MaxLV,Prerequisite Skill-ID-1,Prerequisite Skill-ID-1-Lv,PrereqSkill-ID-2,PrereqSkill-ID-2-Lv,PrereqSkill-ID-3,PrereqSkill-ID-3-Lv,PrereqSkill-ID-4,PrereqSkill-ID-4-Lv,PrereqSkill-ID-5,PrereqSkill-ID-5-Lv //GUILD SKILLNAME#Skill Name#
+// Guild Skill Tree Database
+//
+// Structure of Database:
+// SkillID,MaxLv,Prerequisite SkillID1,Prerequisite SkillLv1,PrereqSkillID2,PrereqSkillLv2,PrereqSkillID3,PrereqSkillLv3,PrereqSkillID4,PrereqSkillLv4,PrereqSkillID5,PrereqSkillLv5	//GUILD SKILLNAME#Skill Name#
+//
+// 01. SkillID                  Skill ID of the guild skill.
+// 02. MaxLv                    Maximum level of the guild skill.
+// 03. Prerequisite SkillID     Guild skill required for the skill to become available.
+// 04. Prerequisite SkillLv     Level of the required guild skill.
+// ...
+//
+// NOTE: MAX_GUILD_SKILL_REQUIRE (typically 5) ID/Lv pairs must be specified.
+
 
 10000,1,0,0,0,0,0,0,0,0,0,0	//GD_APPROVAL#Official Guild Approval#
 10001,1,10000,1,0,0,0,0,0,0,0,0	//GD_KAFRACONTRACT#Contract with Kafra#
diff --git a/db/homun_skill_tree.txt b/db/homun_skill_tree.txt
index e606924c0..2f889fdaf 100644
--- a/db/homun_skill_tree.txt
+++ b/db/homun_skill_tree.txt
@@ -1,4 +1,18 @@
-//CLass,Skill-ID,MaxLV,Prerequisite Skill-ID-1,Prerequisite Skill-ID-1-Lv,PrereqSkill-ID-2,PrereqSkill-ID-2-Lv,PrereqSkill-ID-3,PrereqSkill-ID-3-Lv,PrereqSkill-ID-4,PrereqSkill-ID-4-Lv,PrereqSkill-ID-5,PrereqSkill-ID-5-Lv//CLASS_SKILLNAME#Skill Name#
+// Homunculus Skill Tree Database
+//
+// Structure of Database:
+// Class,SkillID,MaxLv[,JobLevel],Prerequisite SkillID1,Prerequisite SkillLv1,PrereqSkillID2,PrereqSkillLv2,PrereqSkillID3,PrereqSkillLv3,PrereqSkillID4,PrereqSkillLv4,PrereqSkillID5,PrereqSkillLv5 //SKILLNAME#Skill Name#
+//
+// 01. Class                    Homunculus ID.
+// 02. SkillID                  Skill ID of the homunuculus skill.
+// 03. MaxLv                    Maximum level of the homunuculus skill.
+// 04. JobLevel                 Job level required for the skill to become available (optional, reserved, not used by server).
+// 05. Prerequisite SkillID     Homunculus skill required for the skill to become available.
+// 06. Prerequisite SkillLv     Level of the required homunculus skill.
+// ...
+//
+// NOTE: MAX_PC_SKILL_REQUIRE (typically 5) ID/Lv pairs must be specified.
+
 //Lif
 6001,8001,5,0,0,0,0,0,0,0,0,0,0 //HLIF_HEAL
 6001,8002,5,8001,3,0,0,0,0,0,0,0,0 //HLIF_AVOID
@@ -12,7 +26,7 @@
 6003,8010,5,8009,3,0,0,0,0,0,0,0,0 //HFLI_FLEET
 6003,8011,5,8010,3,0,0,0,0,0,0,0,0 //HFLI_SPEED
 //Vanilmirth
-6004,8013,5,0,0,0,0,0,0,0,0,0,0 //HVAN_CAPRICE,
+6004,8013,5,0,0,0,0,0,0,0,0,0,0 //HVAN_CAPRICE
 6004,8014,5,8013,3,0,0,0,0,0,0,0,0 //HVAN_CHAOTIC
 6004,8015,5,8013,5,0,0,0,0,0,0,0,0 //HVAN_INSTRUCT
 //Lif2
@@ -28,7 +42,7 @@
 6007,8010,5,8009,3,0,0,0,0,0,0,0,0 //HFLI_FLEET
 6007,8011,5,8010,3,0,0,0,0,0,0,0,0 //HFLI_SPEED
 //Vanilmirth2
-6008,8013,5,0,0,0,0,0,0,0,0,0,0 //HVAN_CAPRICE,
+6008,8013,5,0,0,0,0,0,0,0,0,0,0 //HVAN_CAPRICE
 6008,8014,5,8013,3,0,0,0,0,0,0,0,0 //HVAN_CHAOTIC
 6008,8015,5,8013,5,0,0,0,0,0,0,0,0 //HVAN_INSTRUCT
 //Lif_H
@@ -47,7 +61,7 @@
 6011,8011,5,8010,3,0,0,0,0,0,0,0,0 //HFLI_SPEED
 6011,8012,3,0,0,0,0,0,0,0,0,0,0 //HFLI_SBR44
 //Vanilmirth_H
-6012,8013,5,0,0,0,0,0,0,0,0,0,0 //HVAN_CAPRICE,
+6012,8013,5,0,0,0,0,0,0,0,0,0,0 //HVAN_CAPRICE
 6012,8014,5,8013,3,0,0,0,0,0,0,0,0 //HVAN_CHAOTIC
 6012,8015,5,8013,5,0,0,0,0,0,0,0,0 //HVAN_INSTRUCT
 6012,8016,3,0,0,0,0,0,0,0,0,0,0 //HVAN_EXPLOSION
@@ -67,7 +81,7 @@
 6015,8011,5,8010,3,0,0,0,0,0,0,0,0 //HFLI_SPEED
 6015,8012,3,0,0,0,0,0,0,0,0,0,0 //HFLI_SBR44
 //Vanilmirth2_H
-6016,8013,5,0,0,0,0,0,0,0,0,0,0 //HVAN_CAPRICE,
+6016,8013,5,0,0,0,0,0,0,0,0,0,0 //HVAN_CAPRICE
 6016,8014,5,8013,3,0,0,0,0,0,0,0,0 //HVAN_CHAOTIC
 6016,8015,5,8013,5,0,0,0,0,0,0,0,0 //HVAN_INSTRUCT
 6016,8016,3,0,0,0,0,0,0,0,0,0,0 //HVAN_EXPLOSION
diff --git a/db/homunculus_db.txt b/db/homunculus_db.txt
index 3ec8f0a88..5ce9d8b73 100644
--- a/db/homunculus_db.txt
+++ b/db/homunculus_db.txt
@@ -1,6 +1,23 @@
-//Legend: b: base, gn: growth min, gx: growth max, en: evolution min, ex: evolution max
-//Note: Only the growth values are in a 1/10 scale, the other stats are 1/1 (eg: 5 gmAGI means 0.5 agi)
-//class,evo_class,name,foodID,hungryDelay,base_size,evo_size,race,element,bASPD,bHP,bSP,bSTR,bAGI,bVIT,bINT,bDEX,bLUK,gnHP,gxHP,gnSP,gxSP,gnSTR,gxSTR,gnAGI,gxAGI,gnVIT,gxVIT,gnINT,gxINT,gnDEX,gxDEX,gnLUK,gxLUK,enHP,exHP,enSP,exSP,enSTR,exSTR,enAGI,exAGI,enVIT,exVIT,enINT,exINT,enDEX,exDEX,enLUK,exLUK
+// Homunculus Database
+//
+// Structure of Database:
+// Class,EvoClass,Name,FoodID,HungryDelay,BaseSize,EvoSize,Race,Element,bASPD,bHP,bSP,bSTR,bAGI,bVIT,bINT,bDEX,bLUK,gnHP,gxHP,gnSP,gxSP,gnSTR,gxSTR,gnAGI,gxAGI,gnVIT,gxVIT,gnINT,gxINT,gnDEX,gxDEX,gnLUK,gxLUK,enHP,exHP,enSP,exSP,enSTR,exSTR,enAGI,exAGI,enVIT,exVIT,enINT,exINT,enDEX,exDEX,enLUK,exLUK
+//
+// 01. Class        Homunculus ID.
+// 02. EvoClass     Homunculus ID of the evolved version.
+// 03. Name         Name of the homunculus.
+// 04. FoodID       Item ID of the homunuclus food.
+// 05. HungryDelay  Time interval in milliseconds after which the homunculus' hunger value is altered.
+// 06. BaseSize     Size of the base homunculus class (0 = small, 1 = normal, 2 = large).
+// 07. EvoSize      Size of the evolved homunculus class (0 = small, 1 = normal, 2 = large).
+// 08. Race         Race of the homunculus (0 = formless, 1 = undead, 2 = brute, 3 = plant, 4 = insect, 5 = fish, 6 = demon, 7 = demi-human, 8 = angel, 9 = dragon).
+// 09. Element      Element of the homunculus (0 = neutral, 1 = water, 2 = earth, 3 = fire, 4 = wind, 5 = poison, 6 = holy, 7 = dark, 8 = ghost, 9 = undead).
+//                  The element level is always 1.
+// ...
+//
+// Legend: b: base, gn: growth min, gx: growth max, en: evolution min, ex: evolution max
+// NOTE: Only the growth values are in a 1/10 scale, the other stats are 1/1 (eg: 5 gmAGI means 0.5 agi)
+
 6001,6009,Lif,537,60000,0,1,7,0,700,150,40,17,20,15,35,24,12,60,100,4,9,5,19,5,19,5,19,4,20,6,20,6,20,1,10,10,20,1,5,1,4,1,5,4,10,1,10,1,3
 6002,6010,Amistr,912,60000,0,1,2,0,700,320,10,20,17,35,11,24,12,80,130,1,4,8,20,4,20,4,20,1,10,3,19,3,19,10,20,1,10,1,10,1,5,4,10,1,3,1,4,1,5
 6003,6011,Filir,910,60000,0,1,2,0,700,90,25,29,35,9,8,30,9,45,75,3,6,4,20,8,20,1,10,3,19,4,20,3,19,5,15,5,15,4,10,1,10,1,3,1,4,1,5,1,5
diff --git a/db/item_avail.txt b/db/item_avail.txt
index 614fcc129..a3c7acdfe 100644
--- a/db/item_avail.txt
+++ b/db/item_avail.txt
@@ -1,7 +1,15 @@
-// item id,sprite id
-// Replaces an item client-side while keeping them separate server-side.
+// Item Availability and Alias Database
+//
+// Structure of Database:
+// ItemID,SpriteID
+//
+// 01. ItemID       Item ID to change.
+// 02. SpriteID     Item ID which will be sent to the client instead of ItemID.
+//                  If 0, the item becomes unavailable for use. If item_check is enabled and a player owns such an item, it will be removed upon next login/teleport.
+//
+// NOTE: Replaces an item client-side while keeping them separate server-side.
 // Think of it as a way to disguise items.
-// If 0 is used then item will be disabled.
+
 2240,2241 //Beard - Grampa Beard
 
 //Treasure Hunters Quest Items
diff --git a/db/item_cookie_bag.txt b/db/item_cookie_bag.txt
index 64cfdfe01..eec259183 100644
--- a/db/item_cookie_bag.txt
+++ b/db/item_cookie_bag.txt
@@ -1,4 +1,3 @@
-
 // Cookie Bag Obtainable Items Database
 //
 // Structure of Database:
diff --git a/db/packet_db.txt b/db/packet_db.txt
index b4a45c9f7..f423d1c14 100644
--- a/db/packet_db.txt
+++ b/db/packet_db.txt
@@ -1,10 +1,35 @@
+// Client<->Map Packet Database
+//
+// Structure of Database:
+// PacketType,PacketLength[,Name,FieldIndex1:FieldIndex2:FieldIndex3:...]
+//
+// 01. PacketType       ID of the packet.
+// 02. PacketLength     Length of the packet. If 0, packet is disabled in current packet version. If -1, packet has variable size.
+// 03. Name             Name of the packet parser function (optional, for incoming packets only).
+// 04. FieldIndex       Specifies the offset of a packet field in bytes from the begin of the packet (only specified when Name is given).
+//                      Can be 0, when the layout is not known.
+// ...
+//
+// NOTE: Up to MAX_PACKET_POS (typically 20) field indexes may be used.
+//
 // The packet database allows you to add support for new clients,
 // because packets change every release.
+//
 // Note: Every packet version needs a wanttoconnection specification, since
 // that is the packet used to identify a client's version.
 // If multiple versions have the same connection packet, the higher version
 // will be used (unless the lower one is specified as the default)
-
+//
+// Incoming packets have their parser function and layout specified, which enables
+// them for the current and all higher versions, unless explicitely disabled.
+//
+// Outgoing packets must be specified in order to enable them for the current
+// and all higher versions, unless explocitely disabled. Packets that are not
+// enabled for a packet version are silently discarded when sent as multicast.
+//
+// Every packet version inherits packet definitions from the previous (lower)
+// packet version.
+//
 // Main packet version of the DB to use (default = max available version)
 // Client detection is faster when all clients use this version.
 // Version 23 is the latest Sakexe (above versions are for Renewal clients)