What is the best practice for documenting network protocol?

Question

I have a couple applications that communicate over TCP/UDP sockets. Each one has a different set of commands (protocol) that it follows and different expected returns. I've been trying to compile a list of commands with parameters, types, return values, error codes, exceptions, etc. but I'm stuck on formatting it.

Example command (a simple one):

LISTPLAYERS:ROOMID
// ROOMID is an integer
// Returns list of players in format:
//  PLAYERID:PLAYERNAME
// Until ended with: 
//  OK

What is the best method for documenting this? (I'm asking for documentation standards, formatting ideas, programs, etc.)

Edit: I found an example of the ICQ protocol. I'm looking for a standard for documenting communication like this, or at least a better way to do it.

Answer 1

I don't know if this is really an answer to you question, but try to use Doxygen comment:

/**
 * This function performs an action, blabla...
 * @param Par1 (in)  is used to ...
 * @param Par2 (out) is use to return ...
 * @return bool if succeeded
 */
bool functionName(int Par1, char* Par2)
{
    // function implementation
}

See more comment syntax

And try to see some example output automatic generated by this comment blocks...

The automatic document generation does support C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D. But you can use the comment syntax to comment any language...

Answer 2

My research was on API documentation rather than protocol documentation, but I can recommend two things to take into account:

1) Many people will never read the docs for a command/concept and will assume they understand it based on its name, especially if it is intuitive.

2) Whoever will read it, will skim, and will lose interest if anything early on seems too intuitive.

Therefore, here are a few tips

• Very clearly mark the directives - things that are very critical for the client to know. Any trick in the book is legitimate. Use lots of stars, exclamation points, text like "WARNING!!! Note that..." and so on. Even all caps. Anything you can do to convey the really critical things is important.

• Think about organization and assume skimming rather than careful reading. Place the important directives first. Make sure to state your sentences with directive first, explanation later. For example: "DO X because bla bla bla" rather than "Bla bla bla bla bla, therefore do X".

Answer 3

I have always liked the RFC style:

TCP Header Format

    0                   1                   2                   3   
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          Source Port          |       Destination Port        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                        Sequence Number                        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                    Acknowledgment Number                      |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Data |           |U|A|P|R|S|F|                               |
   | Offset| Reserved  |R|C|S|S|Y|I|            Window             |
   |       |           |G|K|H|T|N|N|                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |           Checksum            |         Urgent Pointer        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                    Options                    |    Padding    |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                             data                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                            TCP Header Format

          Note that one tick mark represents one bit position.

                               Figure 3.

  Source Port:  16 bits

    The source port number.

  Destination Port:  16 bits

    The destination port number.

From: http://www.faqs.org/rfcs/rfc793.html

Just make sure you specify the endianess as well somewhere in the document.