Issue 116 - Document the libadblockplus API

include/AdblockPlus/AppInfo.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
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
  *
  * You should have received a copy of the GNU General Public License
  * along with Adblock Plus.  If not, see <http://www.gnu.org/licenses/>.
  */
 
 #ifndef ADBLOCK_PLUS_APP_INFO_H
 #define ADBLOCK_PLUS_APP_INFO_H
 
 #include <string>
 
 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) {}
   };
 }
 
 #endif