Issue 116 - Document the libadblockplus API

include/AdblockPlus/JsEngine.h

 /*
  * This file is part of Adblock Plus <http://adblockplus.org/>,
  * Copyright (C) 2006-2014 Eyeo GmbH
  *
  * Adblock Plus is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License version 3 as
  * published by the Free Software Foundation.
  *
  * Adblock Plus is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ skipping 27 matching lines @@
   class Isolate;
   class Value;
   class Context;
   template<class T> class Handle;
   typedef Handle<Value>(*InvocationCallback)(const Arguments &args);
 }
 
 namespace AdblockPlus
 {
   class JsEngine;
+
+  /**
+   * Shared smart pointer to a `JsEngine` instance.
+   */
   typedef std::tr1::shared_ptr<JsEngine> JsEnginePtr;
 
   /**
    * JavaScript engine used by `FilterEngine`, wraps v8.
    */
   class JsEngine : public std::tr1::enable_shared_from_this<JsEngine>
   {
     friend class JsValue;
     friend class JsContext;
 
   public:
     /**
      * Event callback function.
      */
     typedef std::tr1::function<void(JsValueList& params)> EventCallback;
 
     /**
      * Maps events to callback functions.
      */
     typedef std::map<std::string, EventCallback> EventMap;
 
     /**
      * Creates a new JavaScript engine instance.
-     * @param appInfo Information about the app, used for update checks.
+     * @param appInfo Information about the app.
      * @return New `JsEngine` instance.
      */
     static JsEnginePtr New(const AppInfo& appInfo = AppInfo());
 
     /**
      * Registers the callback function for an event.
-     * @param eventName Event name.
+     * @param eventName Event name. Note that this can be any string - it's a
+     *        general purpose event handling mechanism.
      * @param callback Event callback function.
      */
     void SetEventCallback(const std::string& eventName, EventCallback callback);
 
     /**
      * Removes the callback function for an event.
      * @param eventName Event name.
      */
     void RemoveEventCallback(const std::string& eventName);
 
@@ skipping 123 matching lines @@
     FileSystemPtr fileSystem;
     WebRequestPtr webRequest;
     LogSystemPtr logSystem;
     v8::Isolate* isolate;
     V8ValueHolder<v8::Context> context;
     EventMap eventCallbacks;
   };
 }
 
 #endif