doc: add propertylvalue.md (#925)

Documents the helper class `Napi::Object::PropertyLValue`.

Fixes: #924

Author: gabrielschulhof

doc/object.md

@@ -232,28 +232,31 @@ void Napi::Object::DefineProperties (____ properties)
 
 Defines properties on the object.
 
-### Operator[]()
+### operator\[\]()
 
 ```cpp
 Napi::PropertyLValue<std::string> Napi::Object::operator[] (const char* utf8name);
 ```
 - `[in] utf8name`: UTF-8 encoded null-terminated property name.
 
-Returns a [`Napi::PropertyLValue`](propertylvalue.md) as the named property or sets the named property.
+Returns a [`Napi::Object::PropertyLValue`](propertylvalue.md) as the named
+property or sets the named property.
 
 ```cpp
 Napi::PropertyLValue<std::string> Napi::Object::operator[] (const std::string& utf8name);
 ```
 - `[in] utf8name`: UTF-8 encoded property name.
 
-Returns a [`Napi::PropertyLValue`](propertylvalue.md) as the named property or sets the named property.
+Returns a [`Napi::Object::PropertyLValue`](propertylvalue.md) as the named
+property or sets the named property.
 
 ```cpp
 Napi::PropertyLValue<uint32_t> Napi::Object::operator[] (uint32_t index);
 ```
 - `[in] index`: Element index.
 
-Returns a [`Napi::PropertyLValue`](propertylvalue.md) or sets an indexed property or array element.
+Returns a [`Napi::Object::PropertyLValue`](propertylvalue.md) or sets an
+indexed property or array element.
 
 ```cpp
 Napi::Value Napi::Object::operator[] (const char* utf8name) const;

doc/propertylvalue.md

@@ -0,0 +1,50 @@
+# PropertyLValue 
+
+The `Napi::Object::PropertyLValue` class is a helper class provided by
+`Napi::Object` to allow more intuitive assignment of properties.
+
+## Example
+```cpp
+#include <napi.h>
+
+using namespace Napi;
+
+Void Init(Env env) {
+  // Create a new instance
+  Object obj = Object::New(env);
+
+  // Assign a value to a property. 
+  obj["hello"] = "world";
+}
+```
+
+In the above example, `obj["hello"]` returns a `Napi::Object::PropertyLValue`
+whose `operator=()` method accepts a string which will become the value of the
+"hello" property of the newly created object.
+
+In general, `obj[key] = value` is the equivalent of `obj.Set(key, value)`, where
+the types of `key` and `value` are all those supported by
+[`Napi::Object::Set()`](object.md#set).
+
+## Methods
+
+### operator Value()
+
+```cpp
+operator Value() const;
+```
+
+Implicitly casts this `Napi::Object::PropertyLValue` to a `Napi::Value`.
+
+### operator =()
+
+```cpp
+template <typename ValueType>
+PropertyLValue& operator =(ValueType value);
+```
+
+* `[in] value` a value to assign to the property referred to by the
+  `Napi::Object::PropertyLValue`. The type of the value is one of the types
+  supported by the second parameter of [`Napi::Object::Set()`](object.md#set).
+
+Returns a self-reference.