   ###*
   * Retrieve full list of calendars
   *
-  * @param {UoACalendarClient~listCalendarsSuccess} onSuccess - Success callback function
-  * @param {UoACalendarClient~listCalendarsError} onError - Error callback function
+  * @param {onListCalendarsSuccess} onSuccess - Success callback function
+  * @param {onListCalendarsError} onError - Error callback function
+  * @example
+  * client.listCalendars(
+  *   function(res, data) // onSuccess callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   },
+  *   function(res, data) // onError callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   }
+  * );
   ###
 
   listCalendars: (onSuccess, onError) ->
     @sendRequest('/calendars/', 'GET', 0, onSuccess, onError)
 
   ###*
-  * @callback UoACalendarClient~listCalendarsSuccess
-  * @param {res} Response
-  * @param {data} Deserialized data
-  ###
-
-  ###*
-  * @callback UoACalendarClient~listCalendarsError
-  * @param {res} Response
-  * @param {data} ?
+  * Callback, returns an array of calendars.
+  *
+  * @callback onListCalendarsSuccess
+  * @param {HttpResponse} res - HTTP response object.
+  * @param {ErrorMessage} data - An array of calendar JSON objects, with name and id key value pairs.
+  *
+  * @example <caption>Example output</caption>
+  * res: {"offset":5216,"readable":true,"_events":{},"statusCode":200,"headers":{"content-type":"application/json"}}
+  * data: [{"name":"Public holidays","id":1},{"name":"CompSci exam dates","id":2},{"name":"Movie release dates","id":3}]
+  ###
+
+  ###*
+  * Callback function, executed when adding calendar failed.
+  *
+  * @callback onListCalendarsError
+  * @param {HttpResponse} res - HTTP response
+  * @param {ErrorMessage} data - Error message.
+  *
+  * @example <caption>Example output</caption>
+  * todo: insert example
   ###
 
   ###*
   * Retrieve a particular calendar
-  * @param {Number} id - id of the calendar
-  * @param {UoACalendarClient~getCalendarSuccess} onSuccess - Success callback function
-  * @param {UoACalendarClient~getCalendarError} onError - Error callback function
+  * @param {number} id - id of the calendar
+  * @param {onGetCalendarSuccess} onSuccess - Success callback function
+  * @param {onGetCalendarError} onError - Error callback function
+  * @example
+  * var calendarId = 1;
+  * client.getCalendar(calendarId,
+  *   function(res, data) // onSuccess callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   },
+  *   function(res, data) // onError callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   }
+  * );
   ###
 
   getCalendar: (id, onSuccess, onError) ->
     @sendRequest('/calendars/' + id + '/', 'GET', 0, onSuccess, onError)
 
   ###*
-  * @callback UoACalendarClient~getCalendarSuccess
-  * @param {res} Response
-  * @param {data} Deserialized data
-  ###
-
-  ###*
-  * @callback UoACalendarClient~getCalendarError
-  * @param {res} Response
-  * @param {data} ?
+  * Callback, returns particular calendar including its name and id. TODO: return custom fields here.
+  *
+  * @callback onGetCalendarSuccess
+  * @param {HttpResponse} res - HTTP response
+  * @param {Object.<{name: string, id: number}>} data - calendar with name and id
+  *
+  * @example <caption>Example output</caption>
+  * res: {"offset":5216,"readable":true,"_events":{},"statusCode":200,"headers":{"content-type":"application/json"}}
+  * data: {"name":"My Calendar","id":84}
+  ###
+
+  ###*
+  * @callback onGetCalendarError
+  * @param {HttpResponse} res - HTTP response
+  * @param {ErrorMessage} data - detail of what went wrong
+  *
+  * @example <caption>Item doesn't exist</caption>
+  * res: {"offset":22,"readable":true,"_events":{},"statusCode":404,"headers":{"content-type":"application/json"}}
+  * data: {detail: "Not found"}
+  *
+  * @example <caption>No permission to access item</caption>
+  * res: {"offset":63,"readable":true,"_events":{},"statusCode":403,"headers":{"content-type":"application/json"}}
+  * data: {detail: "You do not have permission to perform this action."}
   ###
 
   ###*
   * Add a new calendar providing the new calendar's name
-  * @param {String} name - Name of calendar
-  * @param {UoACalendarClient~addCalendarSuccess} onSuccess - Success callback function
-  * @param {UoACalendarClient~addCalendarError} onError - Error callback function
+  * @param {string} name - Name of calendar
+  * @param {onAddCalendarSuccess} onSuccess - Success callback function
+  * @param {onAddCalendarError} onError - Error callback function
+  *
+  * @example
+  * var name = "My calendar";
+  * client.addCalendar(name,
+  *   function(res, data) // onSuccess callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   },
+  *   function(res, data) // onError callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   }
+  * );
   ###
 
   addCalendar: (name, onSuccess, onError) ->
     @sendRequest('/calendars/', 'POST', {name: name}, onSuccess, onError)
 
   ###*
-  * @callback UoACalendarClient~addCalendarSuccess
-  * @param {res} Response
-  * @param {data} Deserialized data
-  ###
-
-  ###*
-  * @callback UoACalendarClient~addCalendarError
-  * @param {res} Response
-  * @param {data} ?
+  * Callback function, executed when calendar successfully added.
+  *
+  * @callback onAddCalendarSuccess
+  * @param {HttpResponse} res - HTTP response
+  * @param {Array.<{name: string, id: number}>} data - An array of calendar JSON objects, with name and id key value pairs.
+  *
+  * @example <caption>Example output</caption>
+  * res: {"offset":26,"readable":true,"_events":{},"statusCode":201,"headers":{"content-type":"application/json"}}
+  * data: {"name":"My calendar","id":194}
+  ###
+
+  ###*
+  * Callback function, executed when adding calendar failed.
+  *
+  * @callback onAddCalendarError
+  * @param {HttpResponse} res - HTTP response.
+  * @param {ErrorMessage} data - Error message.
+  *
+  * @example <caption>Example output</caption>
+  * todo: insert example
   ###
 
   ###*
   * Delete an existing calendar given its id
-  * @param {Number} id - id of calendar
-  * @param {UoACalendarClient~deleteCalendarSuccess} onSuccess - Success callback function
-  * @param {UoACalendarClient~deleteCalendarError} onError - Error callback function
+  * @param {number} id - id of calendar
+  * @param {onDeleteCalendarSuccess} onSuccess - Success callback function
+  * @param {onDeleteCalendarError} onError - Error callback function
+  *
+  * @example
+  * var calendarId = 1;
+  * client.deleteCalendar(calendarId,
+  *   function(res, data) // onSuccess callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   },
+  *   function(res, data) // onError callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   }
+  * );
   ###
 
   deleteCalendar: (id, onSuccess, onError) ->
     @sendRequest('/calendars/' + id + '/', 'DELETE', {}, onSuccess, onError)
 
   ###*
-  * @callback UoACalendarClient~deleteCalendarSuccess
-  * @param {res} Response
-  * @param {data} Deserialized data
-  ###
-
-  ###*
-  * @callback UoACalendarClient~deleteCalendarError
-  * @param {res} Response
-  * @param {data} ?
+  * Callback, executed when calendar successfully deleted.
+  *
+  * @callback onDeleteCalendarSuccess
+  * @param {HttpResponse} res - HTTP response
+  * @param {Object.<{}>} data - Empty JSON object
+  *
+  * @example <caption>Example output</caption>
+  * res: {"offset":0,"readable":true,"_events":{},"statusCode":204,"headers":{"content-type":"text/plain; charset=UTF-8"}}
+  * data: {}
+  ###
+
+  ###*
+  * Callback function, executed when delete calendar failed.
+  *
+  * @callback onDeleteCalendarError
+  * @param {HttpResponse} res - HTTP response
+  * @param {ErrorMessage} data - Error message.
+  *
+  * @example <caption>Example output</caption>
+  * todo: insert example
   ###
 
   ###*
   * Retrieve the full list of events of an existing calendar given its id
-  * @param {Number} calendarId - Id of calendar
-  * @param {UoACalendarClient~listEventsSuccess} onSuccess - Success callback function
-  * @param {UoACalendarClient~listEventsError} onError - Error callback function
+  * @param {number} calendarId - Id of calendar
+  * @param {onListEventsSuccess} onSuccess - Success callback function
+  * @param {onListEventsError} onError - Error callback function
+  *
+  * @example
+  * var calendarId = 1;
+  * client.listEvents(calendarId,
+  *   function(res, data) // onSuccess callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   },
+  *   function(res, data) // onError callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   }
+  * );
   ###
 
   listEvents: (calendarId, onSuccess, onError) ->
     @sendRequest('/calendars/' + calendarId + '/events/', 'GET', 0, onSuccess, onError)
 
   ###*
-  * @callback UoACalendarClient~listEventsSuccess
-  * @param {res} Response
-  * @param {data} Deserialized events dictionary
-  ###
-
-  ###*
-  * @callback UoACalendarClient~listEventsError
-  * @param {res} Response
-  * @param {data} ?
+  * Callback, executed when list events successful, data parameter contains list of events.
+  *
+  * @callback onListEventsSuccess
+  * @param {HttpResponse} res - HTTP response
+  * @param {Array.<{id:number, title: string, description: string, start: string, end: string, allDay: boolean, url: string, status: string, reminder: string, todo: boolean, location: string, summary: string, lastUpdate: string}>} data - An array of events
+  *
+  * @example <caption>Example output</caption>
+  * res: {"offset":2,"readable":true,"_events":{},"statusCode":200,"headers":{"content-type":"application/json"}}
+  * data: [{"id":3,"title":"The Force Awakens","description":"","start":"2014-12-18T21:40:00Z","end":"2014-12-18T22:00:00Z",
+  *   "allDay":false,"url":"http://www.starwars.com/the-force-awakens/trailers/","status":null,"reminder":null,
+  *   "todo":false,"location":null,"summary":null,"lastUpdate":"2014-12-16T21:26:04Z"},
+  *  {"id":5,"title":"HoloLens","description":"","start":"2014-12-17T04:00:00Z","end":"2014-12-17T05:00:00Z",
+  *   "allDay":false,"url":"http://www.microsoft.com/microsoft-hololens/en-us","status":null,"reminder":null,
+  *   "todo":false,"location":null,"summary":null,"lastUpdate":"2014-12-18T20:54:58Z"}]
+  ###
+
+  ###*
+  * Callback function, executed when list events failed.
+  *
+  * @callback onListEventsError
+  * @param {HttpResponse} res - HTTP response
+  * @param {ErrorMessage} data - Error message.
+  *
+  * @example <caption>Example output</caption>
+  * todo: insert example
   ###
 
   ###*
   * Add an event to a particular calendar. Your own data fields can be added to the JSON event object, for
   * example, if you wanted to add an 'exercise' type to an event do the following: {"title": "My calendar", "exercise": "Run"}
   *
-  * @param {Number} calendarId - Id of calendar
+  * @param {number} calendarId - Id of calendar
   * @param {Object} event - Event JSON object
-  * @param {String} event.title - Event title
-  * @param {String=} event.description - Event description
-  * @param {String=} event.location - Event location
-  * @param {String=} event.summary - Event summary
-  * @param {Date=} event.start - Event start date & time
+  * @param {string} event.title - Event title
+  * @param {string=} event.description - Event description
+  * @param {string=} event.location - Event location
+  * @param {string=} event.summary - Event summary
+  * @param {Date} event.start - Event start date & time
   * @param {Date=} event.end - Event end date & time
-  * @param {String=} event.status - Event status
-  * @param {String=} event.reminder - Event reminder
-  * @param {Boolean=} event.todo - Whether event still to be done
-  * @param {Boolean=} event.allDay - Whether event occurs all day
-  * @param {String=} event.url - Event url
-  * @param {UoACalendarClient~addEventSuccess} onSuccess - Success callback function
-  * @param {UoACalendarClient~addEventError} onError - Error callback function
+  * @param {string=} event.status - Event status
+  * @param {string=} event.reminder - Event reminder
+  * @param {boolean=} event.todo - Whether event still to be done
+  * @param {boolean=} event.allDay - Whether event occurs all day
+  * @param {string=} event.url - Event url
+  * @param {onAddEventSuccess} onSuccess - Success callback function
+  * @param {onAddEventError} onError - Error callback function
+  *
+  * @example <caption>Minimal example of how to add an event to a calendar, only title is mandatory.</caption>
+  * var calendarId = 1;
+  * var event = {"title": "Auckland Marathon", "start": new Date(2016, 11, 1, 6, 0, 0)};
+  * client.addEvent(calendarId, event,
+  *   function(res, data) // onSuccess callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   },
+  *   function(res, data) // onError callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   }
+  * );
+  *
+  * @example <caption>Complete example of how to add an event to a calendar.</caption>
+  * var calendarId = 1;
+  * var event = {"title": "Auckland Marathon", "description": "Running marathon today",
+  *              "location": "King Edward Parade, Devonport", "summary": "Marathon",
+  *              "start": new Date(2016, 11, 1, 6, 0, 0), "end": new Date(2016, 11, 1, 8, 30, 0),
+  *              "status": "active", "todo": true, "addDay": false, "url": "https://www.aucklandmarathon.co.nz/"};
+  * client.addEvent(calendarId, event,
+  *   function(res, data) // onSuccess callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   },
+  *   function(res, data) // onError callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   }
+  * );
+  *
+  * @example <caption>Example of adding an event with a custom data field. The data field 'exercise' is custom.</caption>
+  * var calendarId = 1;
+  * var event = {"title": "Auckland Marathon", "start": new Date(2016, 11, 1, 6, 0, 0), "exercise": "run"};
+  * client.addEvent(calendarId, event,
+  *   function(res, data) // onSuccess callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   },
+  *   function(res, data) // onError callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   }
+  * );
   ###
 
   addEvent: (calendarId, event, onSuccess, onError) ->
     @sendRequest('/calendars/' + calendarId + '/events/', 'POST', event, onSuccess, onError)
 
   ###*
-  * Event object
-  *
-  * @class Event
-  ###
-
-  ###*
-  * @callback UoACalendarClient~addEventSuccess
-  * @param {res} Response
-  * @param {data} Deserialized events dictionary
-  ###
-
-  ###*
-  * @callback UoACalendarClient~addEventError
-  * @param {res} Response
-  * @param {data} ?
-  ###
+  * Callback, executed when event added successfully.
+  *
+  * @callback onAddEventSuccess
+  * @param {HttpResponse} res - HTTP response
+  * @param {Object.<{id:number, title: string, description: string, start: string, end: string, allDay: boolean, url: string, status: string, reminder: string, todo: boolean, location: string, summary: string, lastUpdate: string}>} data - JSON object with event id
+  *
+  * @example <caption>Example output</caption>
+  * res: {"offset":243,"readable":true,"_events":{},"statusCode":201,"headers":{"content-type":"application/json"}}
+  * data: {"id":2699,"title":"cool event","description":null,"start":"2015-11-17T23:49:18.747000Z","end":null,
+  *        "allDay":false,"url":null,"status":null,"reminder":null,"todo":false,"location":null,"summary":null,
+  *        "lastUpdate":"2015-11-17T23:49:18.899897Z"}
+  ###
+
+  ###*
+  * Callback function, executed when adding an event failed.
+  *
+  * @callback onAddEventError
+  * @param {HttpResponse} res - HTTP response
+  * @param {ErrorMessage} data - Error message.
+  *
+  * @example <caption>Example output when title and start date not specified</caption>
+  * res: {"offset":73,"readable":true,"_events":{},"statusCode":400,"headers":{"content-type":"application/json"}}
+  * data: {"title":"This field is required.", "start":"This field is required."} todo: remove arrays from
+  *
+  * @example <caption>Example output when calendar doesn't exist</caption>
+  * res: {"offset":73,"readable":true,"_events":{},"statusCode":400,"headers":{"content-type":"application/json"}}
+  * data: {detail: "Calendar with id -1 doesn't exist"} todo: chang error message
+  *
+  * @example <caption>Example where date has wrong format</caption>
+  * res: {"offset":122,"readable":true,"_events":{},"statusCode":400,"headers":{"content-type":"application/json"}}
+  * data: {"start":"Datetime has wrong format. Use one of these formats instead: YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z]"}
+  ###
+
+  #add event success
+  #{"offset":37,"readable":true,"_events":{},"statusCode":400,"headers":{"content-type":"application/json"}}
+  #"{\"start\":[\"This field is required.\"]}"
 
   ###*
   * Delete an existing event from a calendar giving their ids
   *
-  * @param {Number} calendarId - id of calendar
-  * @param {Number} eventId - id of event
-  * @param {UoACalendarClient~deleteEventSuccess} onSuccess - Success callback function
-  * @param {UoACalendarClient~deleteEventError} onError - Error callback function
+  * @param {number} calendarId - id of calendar
+  * @param {number} eventId - id of event
+  * @param {onDeleteEventSuccess} onSuccess - Success callback function
+  * @param {onDeleteEventError} onError - Error callback function
+  *
+  * @example
+  * var calendarId = 1;
+  * var eventId = 2;
+  * client.deleteEvent(calendarId, eventId,
+  *   function(res, data) // onSuccess callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   },
+  *   function(res, data) // onError callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   }
+  * );
   ###
 
   deleteEvent: (calendarId, eventId, onSuccess, onError) ->
     @sendRequest('/calendars/' + calendarId + '/events/' + eventId + '/', 'DELETE', 0, onSuccess, onError)
 
-# Update an existing event from a calendar giving their IDs
-#
-# ```javascript
-# client.updateEvent(calendarId, eventId, { title: "Event Title", ... }
-#   // onSuccess callback
-#   function(res, data) {
-#       // response
-#       console.log(res);
-#       // deserialized updated event object data
-#       console.log(data);
-#   },
-#   // onError callback
-#   function(res, data) {
-#       ...
-#   }
-# );
-# ```
-#
+  ###*
+  * Callback, executed when event successfully deleted.
+  *
+  * @callback onDeleteEventSuccess
+  * @param {HttpResponse} res - HTTP response
+  * @param {Array} data - empty array
+  *
+  * @example <caption>Example output</caption>
+  * res: {"offset":2,"readable":true,"_events":{},"statusCode":200,"headers":{"content-type":"application/json"}}
+  * data: []
+  ###
+
+  ###*
+  * Callback function, executed when deleting an event failed.
+  *
+  * @callback onDeleteEventError
+  * @param {HttpResponse} res - HTTP response
+  * @param {ErrorMessage} data - Error message.
+  *
+  * @example <caption>Example output</caption>
+  * todo: insert example
+  ###
+
+
+  ###*
+  *  Update an existing event from a calendar giving their IDs
+  *
+  * @param {number} calendarId - id of calendar
+  * @param {number} eventId - id of event
+  * @param {Object} event - Event JSON object
+  * @param {string} event.title - Event title
+  * @param {string=} event.description - Event description
+  * @param {string=} event.location - Event location
+  * @param {string=} event.summary - Event summary
+  * @param {Date} event.start - Event start date & time
+  * @param {Date=} event.end - Event end date & time
+  * @param {string=} event.status - Event status
+  * @param {string=} event.reminder - Event reminder
+  * @param {boolean=} event.todo - Whether event still to be done
+  * @param {boolean=} event.allDay - Whether event occurs all day
+  * @param {string=} event.url - Event url
+  * @param {onUpdateEventSuccess} onSuccess - Success callback function
+  * @param {onUpdateEventError} onError - Error callback function
+  *
+  * @example
+  * var calendarId = 1;
+  * var eventId = 2;
+  * var event = {"title": "Auckland Marathon", "description": "Running the marathon now!"};
+  * client.updateEvent(calendarId, eventId, event,
+  *   function(res, data) // onSuccess callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   },
+  *   function(res, data) // onError callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   }
+  * );
+  ###
+
   updateEvent: (calendarId, eventId, event, onSuccess, onError) ->
     @sendRequest('/calendars/' + calendarId + '/events/' + eventId + '/', 'PATCH', event, onSuccess, onError)
 
-# Find events from an existing calendar within a given time range
-#
-# ```javascript
-# client.updateEvent(calendarId, new Date(1977, 5, 25), Date.now(),
-#   // onSuccess callback
-#   function(res, data) {
-#       // response
-#       console.log(res);
-#       // deserialized events dictionary
-#       console.log(data);
-#   },
-#   // onError callback
-#   function(res, data) {
-#       ...
-#   }
-# );
-# ```
-#
+  ###*
+  * Callback, when event updated.
+  *
+  * @callback onUpdateEventSuccess
+  * @param {HttpResponse} res - HTTP response
+  * @param {Array.<{}>} data - ?
+  *
+  * @example <caption>Example output</caption>
+  * res: {"offset":0,"readable":true,"_events":{},"statusCode":204,"headers":{"content-type":"text/plain; charset=UTF-8"}}
+  * data: [{},
+  *        {}]
+  ###
+
+  ###*
+  * Callback function, executed event update failed.
+  *
+  * @callback onUpdateEventError
+  * @param {HttpResponse} res - HTTP response
+  * @param {ErrorMessage} data - Error message.
+  *
+  * @example <caption>Example output</caption>
+  * todo: insert example
+  ###
+
+  ###*
+  *  Find events from an existing calendar within a given time range
+  *
+  * @param {number} calendarId - id of calendar
+  * @param {Date} startDate - date to begin searching
+  * @param {Date} endDate - date to stop searching
+  * @param {onFindEventsSuccess} onSuccess - Success callback function
+  * @param {onFindEventsError} onError - Error callback function
+  *
+  * @example <caption>Find all events in calendar 1 between the day star wars first screened and now.</caption>
+  * var calendarId = 1;
+  * var startDate = new Date(1977, 5, 25); //date star wars first screened!
+  * var endDate = new Date(); //current date and time
+  * client.findEvents(calendarId, startDate, endDate,
+  *   function(res, data) // onSuccess callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   },
+  *   function(res, data) // onError callback
+  *   {
+  *     console.log(res);
+  *     console.log(data);
+  *   }
+  * );
+  ###
+
   findEvents: (calendarId, startDate, endDate, onSuccess, onError) ->
     toUTCString = (date) ->
       return (new Date(date.getTime() + date.getTimezoneOffset() * 60000)).toISOString()

  * that can contain one or more of the following fields.
  *
  * @class
  * @param {String} apiToken - Sets the user's API token used for authentication purposes.
  * @param {String=} host - Authentication server to which the client will connect. Should *NOT* include the URL schema as it defaults to `http`. Defaults to `DEFAULT_HOST`.
  * @param {Number=} port - TCP port from the host to which the client will connect. Defaults to `DEFAULT_PORT`.
  * @alias UoACalendarClient
  ###

  constructor: (apiToken, host, port) ->

  * Return apiToken used by UoACalendarClient instance.
  *
  * @returns {string}
  *
  * @example
  * var apiToken = client.getApiToken();
  ###

  getApiToken: () ->
