Issue 116 - Document the libadblockplus API

include/AdblockPlus/AppInfo.h

Index: include/AdblockPlus/AppInfo.h
===================================================================
--- a/include/AdblockPlus/AppInfo.h
+++ b/include/AdblockPlus/AppInfo.h
@@ -22,14 +22,46 @@
 
 namespace AdblockPlus
 {
+  /**
+   * Information about the app using libadblockplus.
+   */
   struct AppInfo
   {
+    /**
+     * Optional unique ID of the app.
+     */
     std::string id;

[Wladimir Palant, 2014/08/28 17:24:40]

Didn't we want to remove this? This is the ID used by the platform to identify
the app, it makes fairly little sense in libadblockplus... The only place where
this is actually used seems to be the code integrating with the Firefox Add-ons
Manager.

[Felix Dahlke, 2014/08/28 22:56:41]

Yup, came to the same conclusion, but I'd rather not mix such a change with
adding documentation. Created #1284 for that.

+
+    /**
+     * Current version of the app, in
+     * [Mozilla toolkit version format](https://developer.mozilla.org/en/docs/Toolkit_version_format).
+     */
     std::string version;
+
+    /**
+     * Name of the app, e.g.\ _adblockplus_.

[Wladimir Palant, 2014/08/28 17:24:40]

This should stress the fact that it is a codename, not the user-visible name.
Also, please don't give embedders the idea to actually use "adblockplus" here -
"mygreatapp" should be better.

[Felix Dahlke, 2014/08/28 22:56:41]

Done.

+     */
     std::string name;
+
+    /**
+     * Name of the platform, e.g.\ _msie64_.

[Wladimir Palant, 2014/08/28 17:24:40]

"platform that the app is running on"

[Felix Dahlke, 2014/08/28 22:56:41]

Done.

+     */
     std::string application;
+
+    /**
+     * Current version of the platform
+     */
     std::string applicationVersion;
+
+    /**
+     * Locale to use, as a
+     * [Mozilla locale code](https://wiki.mozilla.org/L10n:Locale_Codes).
+     */
     std::string locale;
+
+    /**
+     * Whether the app is a development build, the default is `false`.
+     */
     bool developmentBuild;
 
     AppInfo() : developmentBuild(false) {}