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 54 matching lines @@
      */
     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.

[Wladimir Palant, 2014/08/29 18:18:50]

Want to note that currently only one callback can be registered per event?

Probably also a good idea to document the possible events here. Currently the
only event the application would register for directly is "updateAvailable". It
is called with the URL of the update download as the only parameter.

[Wladimir Palant, 2014/09/01 17:36:56]

While I see that "set" makes it fairly obvious that there can be only one event
handler, what about documenting available event types? These need to be
documented somewhere, and this looks like the logical place.

[Felix Dahlke, 2014/09/02 05:24:51]

I don't think it's a good place actually. Logically, FilterEngine (or the JS
code it runs) throws the specific events. As far as JsEngine is concerned, this
is just a general purpose event handling mechanism. Made this a bit clearer in
the comment.

Documenting "updateAvailable" is easy - clients want to use it anyway, so we
should add a setter for it:

https://issues.adblockplus.org/ticket/1296

As for "init" and "updateCheckDone*" -> that's more tricky. We should probably
not document either, since Libadblockplus uses them internally - it will only
end in tears if clients interfere with that. I suggest we prefix them with "_":

https://issues.adblockplus.org/ticket/1297

-     * @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