Issue 116 - Document the libadblockplus API

include/AdblockPlus/JsValue.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 17 matching lines @@
 {
   class Value;
   template<class T> class Handle;
 }
 
 namespace AdblockPlus
 {
   class JsValue;
   class JsEngine;
 
-  typedef std::tr1::shared_ptr<JsValue> JsValuePtr;
-  typedef std::vector<AdblockPlus::JsValuePtr> JsValueList;
   typedef std::tr1::shared_ptr<JsEngine> JsEnginePtr;
 
+  /**
+   * Shared smart pointer to a `JsValue` instance.
+   */
+  typedef std::tr1::shared_ptr<JsValue> JsValuePtr;
+
+  /**
+   * List of JavaScript values.
+   */
+  typedef std::vector<AdblockPlus::JsValuePtr> JsValueList;
+
+  /**
+   * Wrapper for JavaScript objects.

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

"JavaScript values"? This can wrap primitive values as well.

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

This comment hasn't been addressed.

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

Oops, done.

+   * See `JsEngine` for creating `JsValue` objects.
+   */
   class JsValue
   {
     friend class JsEngine;
   public:
     JsValue(JsValuePtr value);
     virtual ~JsValue();
 
     bool IsUndefined() const;
     bool IsNull() const;
     bool IsString() const;
     bool IsNumber() const;
     bool IsBool() const;
     bool IsObject() const;
     bool IsArray() const;
     bool IsFunction() const;
     std::string AsString() const;
     int64_t AsInt() const;
     bool AsBool() const;
     JsValueList AsList() const;
+
+    /**
+     * Returns a list of property names if this is an object (see `IsObject()`).
+     * @return List of property names.
+     */
     std::vector<std::string> GetOwnPropertyNames() const;
+
+    /**
+     * Returns a property value if this is an object (see `IsObject()`).
+     * @param name Property name.
+     * @return Property value, undefined (see `IsUndefined()`) if the property
+     *         does not exist.
+     */
     JsValuePtr GetProperty(const std::string& name) const;
+
+    //@{
+    /**
+     * Sets a property value if this is an object (see `IsObject()`).
+     * @param name Property name.
+     * @param val Property value.
+     */
     void SetProperty(const std::string& name, const std::string& val);
     void SetProperty(const std::string& name, int64_t val);
     void SetProperty(const std::string& name, bool val);
     void SetProperty(const std::string& name, JsValuePtr value);
     inline void SetProperty(const std::string& name, const char* val)
     {
       SetProperty(name, std::string(val));
     }
     inline void SetProperty(const std::string& name, int val)
     {
       SetProperty(name, static_cast<int64_t>(val));
     }
+    //@}
+
+    /**
+     * Returns the value's class name, e.g.\ _Array_ for arrays
+     * (see `IsArray()`).
+     * Technically, this is the name of the function that was used as a
+     * constructor.
+     * @return Class name of the value.
+     */
     std::string GetClass() const;
+
+    /**
+     * Invokes the value as a function (see `IsFunction()`).
+     * @param params Optional list of parameters.
+     * @param thisPtr Optional `this` value.
+     * @return Value returned by the function.
+     */
     JsValuePtr Call(const JsValueList& params = JsValueList(),
         AdblockPlus::JsValuePtr thisPtr = AdblockPlus::JsValuePtr()) const;
+
   protected:
     JsValue(JsEnginePtr jsEngine, v8::Handle<v8::Value> value);
     void SetProperty(const std::string& name, v8::Handle<v8::Value> val);
 
     JsEnginePtr jsEngine;
     V8ValueHolder<v8::Value> value;
   };
 }
 
 #endif