-###
-(c) 2010 Stephane Alnet
-Released under the AGPL3 license
-###
+# esl is a client and a server library for FreeSwitch's ESL protocol
+# (c) 2010 Stephane Alnet
+# Released under the AGPL3 license
+#
+
+#### Overview
+# esl is modelled after Node.js' own httpServer and client.
+# It offers two low-level ESL handlers, createClient() and
+# createServer(), and a higher-level CallServer class.
+#
+# For more information about ESL consult the FreeSwitch wiki
+# [Event Socket](http://wiki.freeswitch.org/wiki/Event_Socket)
+#
+# Typically a client would be used to trigger calls asynchronously
+# (for example in a click-to-dial application); this mode of operation is
+# called "inbound" (to FreeSwitch) in the FreeSwitch documentation.
+#
+# A server will handle calls sent to it using the "socket" diaplan
+# application (called "outbound" mode in the FreeSwitch documentation).
+# The server is available at a pre-defined port which
+# the socket application will specify. See
+# [Event Socket Outbound](http://wiki.freeswitch.org/wiki/Event_Socket_Outbound)
+
+#### Usage
+#
+#     esl = require 'esl'
+#
+# (The library is a plain Node.js module so you can also call
+# it from Javascript. All examples are given using CoffeeScript
+# for simplicity.)
 
 net         = require 'net'
 querystring = require 'querystring'
 util        = require 'util'
 assert      = require 'assert'
 
-# Change from the calling code to enable debugging.
+# If you ever need to debug esl, set
+#
+#     esl.debug = true
+#
+
 exports.debug = false
+
+#### Headers parser
+# ESL framing contains headers and a body.
+# The header must be decoded first to learn
+# the presence and length of the body.
 
 parse_header_text = (header_text) ->
   header_lines = header_text.split("\n")

  unicast_uuid: (uuid,args,cb) ->
    @sendmsg_uuid uuid, 'unicast', args, cb

  # nomedia_uuid:

  # Execute an application for the current UUID (in server/outbound mode)


    @process @headers, body
    @headers = {}

    # Re-parse whatever data was left after the body was
    # fully consumed.
    @capture_headers extra

  # Capture headers, meaning up to the first blank line.
  capture_headers: (data) ->
    header_end = data.indexOf("\n\n")

    # Wait until we reach the end of the header.
    if header_end < 0
      @buffer += data
      return
