Issue 116 - Document the libadblockplus API

include/AdblockPlus/FilterEngine.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 14 matching lines @@
 #include <AdblockPlus/JsEngine.h>
 #include <AdblockPlus/JsValue.h>
 
 #include "tr1_memory.h"
 
 namespace AdblockPlus
 {
   class FilterEngine;
 
   /**
-   * Wrapper for a filter object.
+   * Wrapper for an Adblock Plus filter object.
    */
   class Filter : public JsValue,
                  public std::tr1::enable_shared_from_this<Filter>
   {
   public:
     /**
      * Filter types, see https://adblockplus.org/en/filters.
      */
     enum Type {TYPE_BLOCKING, TYPE_EXCEPTION,
                TYPE_ELEMHIDE, TYPE_ELEMHIDE_EXCEPTION,
                TYPE_COMMENT, TYPE_INVALID};
 
+    /**
+     * Retrieves the type of this filter.
+     * @return Type of this filter.
+     */
     Type GetType();
 
     /**
-     * Checks whether this filter has been added to its subscription.
-     * @return `true` if this filter has been added to its subscription.
+     * Checks whether this filter has been added to the list of custom filters.
+     * @return `true` if this filter has been added.
      */
     bool IsListed();
 
     /**
-     * Adds this filter to its subscription.
+     * Adds this filter to the list of custom filters.
      */
     void AddToList();
 
     /**
-     * Removes this filter from its subscription.
+     * Removes this filter from the list of custom filters.
      */
     void RemoveFromList();
 
     bool operator==(const Filter& filter) const;
 
+    /**
+     * Creates a wrapper for an existing JavaScript filter object.
+     * Normally you shouldn't call this directly, but use
+     * FilterEngine::GetFilter() instead.
+     * @param value JavaScript filter object.
+     */
     Filter(JsValuePtr value);
   };
 
   /**
    * Wrapper for a subscription object.
    */
   class Subscription : public JsValue,
                        public std::tr1::enable_shared_from_this<Subscription>
   {
   public:
     /**
-     * Checks if this subscription has been added to the known subscriptions.
-     * @return `true` if this subscription has been added to the known
-     *         subscriptions.
+     * Checks if this subscription has been added to the list of subscriptions.
+     * @return `true` if this subscription has been added.
      */
     bool IsListed();
 
     /**
-     * Adds this subscription to the known subscriptions.
+     * Adds this subscription to the list of subscriptions.
      */
     void AddToList();
 
     /**
-     * Removes this subscription from the known subscriptions.
+     * Removes this subscription from the list of subscriptions.
      */
     void RemoveFromList();
 
     /**
-     * Updates this subscription, i.e.\ retrieves the latest version from the
+     * Updates this subscription, i.e.\ retrieves the current filters from the
      * subscription URL.
      */
     void UpdateFilters();
 
     /**
-     * Checks if this subscriptions is currently being updated.
-     * @return `true` if this subscriptions is currently being updated.
+     * Checks if the subscription is currently being updated.
+     * @return `true` if the subscription is currently being updated.
      */
     bool IsUpdating();
 
     bool operator==(const Subscription& subscription) const;
 
+    /**
+     * Creates a wrapper for an existing JavaScript subscription object.
+     * Normally you shouldn't call this directly, but use
+     * FilterEngine::GetSubscription() instead.
+     * @param value JavaScript subscription object.
+     */
     Subscription(JsValuePtr value);
   };
 
   /**
    * Shared smart pointer to a `Filter` instance.
    */
   typedef std::tr1::shared_ptr<Filter> FilterPtr;
 
   /**
    * Shared smart pointer to a `Subscription` instance.
    */
   typedef std::tr1::shared_ptr<Subscription> SubscriptionPtr;
 
   /**
-   * Main component of Libadblockplus.
+   * Main component of libadblockplus.
    * It handles:
    * - Filter management and matching.
    * - Subscription management and synchronization.
    * - Update checks for the application.
    */
   class FilterEngine
   {
   public:
     /**
-     * Callback invoked when an update is available.
+     * Callback type invoked when an update is available.
+     * The parameter is optional error message.
      */
     typedef std::tr1::function<void(const std::string&)> UpdaterCallback;
 
     /**
-     * Callback invoked when the filters change.
+     * Callback type invoked when the filters change.
+     * The first parameter is the action event code (see
+     * [FilterNotifier.triggerListeners](https://adblockplus.org/jsdoc/adblockplus/symbols/FilterNotifier.html#.triggerListeners)
+     * for the full list).
+     * The second parameter is the filter/subscription object affected, if any.
      */
     typedef std::tr1::function<void(const std::string&, const JsValuePtr)> FilterChangeCallback;
 
+    /**
+     * Constructor.
+     * @param jsEngine `JsEngine` instance used to run JavaScript code
+     *        internally.
+     */
     explicit FilterEngine(JsEnginePtr jsEngine);
+
+    /**
+     * Retrieves the `JsEngine` instance associated with this `FilterEngine`
+     * instance.
+     */
     JsEnginePtr GetJsEngine() const { return jsEngine; }
 
     /**
      * Checks if this is the first run of the application.
      * @return `true` if the application is running for the first time.
      */
     bool IsFirstRun() const;
 
     /**
      * Retrieves a filter object from its text representation.
      * @param text Text representation of the filter,
      *        see https://adblockplus.org/en/filters.
-     * @return New filter object if the filter wasn't known, otherwise the
-     *         existing one.
+     * @return New `Filter` instance.
      */
     FilterPtr GetFilter(const std::string& text);
 
     /**
      * Retrieves a subscription object for the supplied URL.
      * @param url Subscription URL.
-     * @return New subscription object if the subscription wasn't known,
-     *         otherwise the existing one.
+     * @return New `Subscription` instance.
      */
     SubscriptionPtr GetSubscription(const std::string& url);
 
     /**
-     * Retrieves all known filters.
-     * @return List of known filters.
+     * Retrieves the list of custom filters.
+     * @return List of custom filters.
      */
     std::vector<FilterPtr> GetListedFilters() const;
 
     /**
-     * Retrieves all known subscriptions.
-     * @return List of known subscriptions.
+     * Retrieves all subscriptions.
+     * @return List of subscriptions.
      */
     std::vector<SubscriptionPtr> GetListedSubscriptions() const;
 
     /**
      * Retrieves all recommended subscriptions.
-     * This will parse all subscriptions listed in `subscriptions.xml`.
      * @return List of recommended subscriptions.
      */
     std::vector<SubscriptionPtr> FetchAvailableSubscriptions() const;
 
     /**
      * Checks if any active filter matches the supplied URL.
      * @param url URL to match.
      * @param contentType Content type of the requested resource, possible
      *        values are:
      *        - OTHER
@@ skipping 26 matching lines @@
      *        - SCRIPT
      *        - IMAGE
      *        - STYLESHEET
      *        - OBJECT
      *        - SUBDOCUMENT
      *        - DOCUMENT
      *        - XMLHTTPREQUEST
      *        - OBJECT_SUBREQUEST
      *        - FONT
      *        - MEDIA
-     * @param documentUrls Chain of documents requesting the resource.
-     *        This will typically be the frame structure. If the application is
-     *        not capable of identifying the frame structure, e.g. because it is
-     *        a proxy, it can be approximated using `ReferrerMapping`.
-     * @return Matching filter, or `null` if there was no match.
+     * @param documentUrls Chain of documents requesting the resource, starting
+     *        with the current resource's parent frame, ending with the
+     *        top-level frame.
+     *        If the application is not capable of identifying the frame
+     *        structure, e.g. because it is a proxy, it can be approximated
+     *        using `ReferrerMapping`.
+     * @return Matching filter, or a `null` if there was no match.
      */
     FilterPtr Matches(const std::string& url,
         const std::string& contentType,
         const std::vector<std::string>& documentUrls) const;
 
     /**
-     * Retrieves CSS selectors for all active element hiding filters.
+     * Retrieves CSS selectors for all element hiding filters active on the
+     * supplied domain.
      * @param domain Domain to retrieve CSS selectors for.
      * @return List of CSS selectors.
      */
     std::vector<std::string> GetElementHidingSelectors(const std::string& domain) const;
 
     /**
      * Retrieves a preference value.
      * @param pref Preference name.
      * @return Preference value, or `null` if it doesn't exist.
      */
     JsValuePtr GetPref(const std::string& pref) const;
 
     /**
      * Sets a preference value.
      * @param pref Preference name.
      * @param value New value of the preference.
      */
     void SetPref(const std::string& pref, JsValuePtr value);
 
     /**
-     * Extracts the host from an URL.
+     * Extracts the host from a URL.
      * @param url URL to extract the host from.
      * @return Extracted host.
      */
     std::string GetHostFromURL(const std::string& url);
 
     /**
      * Forces an immediate update check.
-     * @param Optional callback to invoke when updates are available.
+     * `FilterEngine` will automatically check for updates in regular intervals,
+     * so applications should only call this when the user triggers an update
+     * check manually.
+     * @param callback Optional callback to invoke when the update check is
+     *        finished. The string parameter will be empty when the update check
+     *        succeeded, or contain an error message if it failed.
+     *        Note that the callback will be invoked after every update check -
+     *        to react to updates being available, register a callback for the
+     *        "updateAvailable" event (see JsEngine::SetEventCallback()).
      */
     void ForceUpdateCheck(UpdaterCallback callback = 0);
 
     /**
      * Sets the callback invoked when the filters change.
-     * @param The callback to invoke.
+     * @param callback Callback to invoke.
      */
     void SetFilterChangeCallback(FilterChangeCallback callback);
 
     /**
      * Removes the callback invoked when the filters change.
      */
     void RemoveFilterChangeCallback();
 
     /**
      * Compares two version strings in
@@ skipping 16 matching lines @@
     void InitDone(JsValueList& params);
     FilterPtr CheckFilterMatch(const std::string& url,
                                const std::string& contentType,
                                const std::string& documentUrl) const;
     void UpdateCheckDone(const std::string& eventName, UpdaterCallback callback, JsValueList& params);
     void FilterChanged(FilterChangeCallback callback, JsValueList& params);
   };
 }
 
 #endif