* Merged changes up to eAthena 15066.

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

1 files changed, 85 insertions, 0 deletions

diff --git a/doc/packet_struct_notation.txt b/doc/packet_struct_notation.txt
new file mode 100644
index 000000000..4ba30cb00
--- /dev/null
+++ b/doc/packet_struct_notation.txt
@@ -0,0 +1,85 @@
+//===== Athena Doc ========================================
+//= Packet Structure Notation
+//===== By ================================================
+//= Ai4rei
+//===== Version ===========================================
+//= 1.0
+//=========================================================
+//= 1.0 - Initial version.
+//===== Description =======================================
+//= Explanation how packets are and should be documented.
+//=========================================================
+
+This document specifies how packets are and should be documented, to
+keep packet structure comments consistent in the entire codebase. It
+also serves as a guide to those, who are unfamiliar with the general
+packet layout.
+
+All mentioned data types are assumed to be little-endian (least-
+significant byte first, least significant bit last) and of same size
+regardless of architecture.
+
+= Typical description of a packet =
+
+ /// Notifies the client about entering a chatroom (ZC_ENTER_ROOM).
+ /// 00db <packet len>.W <chat id>.L { <role>.L <name>.24B }*
+ /// role:
+ ///     0 = owner (menu)
+ ///     1 = normal
+
+The first line contain a brief description of what the packet does,
+or what it is good for, followed by it's AEGIS name in parentheses;
+first two letters of the AEGIS name specify origin (first letter)
+and destination (second letter) of the packet. If the packet's name
+is not known or is not applicable (eAthena server-server packets),
+specify at least these two letters to indicate the direction of the
+packet. Do not use S(end)/R(ecv) for this, as it is inaccurate and
+location dependent (if the description is copied to different server
+or other RO-related projects, it might change it's meaning).
+
+If there are multiple versions of the packet, the AEGIS name is
+appended to the end of the packet's structure instead. If the name
+did not change between versions, a PACKETVER expression is appended,
+such as (PACKETVER >= 20111111).
+
+Second line describes the packet's field structure, beginning with a
+%04x formatted packet type, followed by the individual fields and
+their types. Each field begins with it's name enclosed in angle
+brackets ( <field name> ) followed by a dot and the data size type.
+Field names should be lower-case and without underscores. If other
+packets already have a field in common, use that name, rather than
+inventing your own (ex. "packet len" and "account id"). Repeated and
+optional fields are designated with curly and square brackets
+respectively, padded with a single space at each side.
+
+Further lines are optional and either include details about the
+the packet's mechanics or further explanation on the packet fields'
+values.
+
+= Packet field data size type =
+
+ B = 1 byte (byte)
+ W = 2 bytes (word)
+ L = 4 bytes (dword)
+ Q = 8 bytes (quad)
+
+ nB = n bytes
+ ?B = variable/unknown amount of bytes
+ nS = n bytes, zero-terminated
+ ?S = variable/unknown amount of bytes, zero-terminated
+
+= Repetition of packet fields =
+
+ {} = repeated block
+ {}* = variable/unknown amount of consecutive blocks
+ {}*n = n times repeated block
+ [] = optional fields
+
+= Packet origin and destination letters =
+
+ A = Account (Login)
+ C = Client
+ H = Character
+ I = Inter
+ S = Server (any type of server)
+ Z = Zone (Map)