PPAPI: Update pp_var.h documentation for Resource vars.

ppapi/api/ppb_var.idl

 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
  * Use of this source code is governed by a BSD-style license that can be
  * found in the LICENSE file.
  */
 
 /**
  * This file defines the <code>PPB_Var</code> struct.
  */
 
 label Chrome {
@@ skipping 11 matching lines @@
    * object, this function will do nothing so you can always call it no matter
    * what the type.
    *
    * @param[in] var A <code>PP_Var</code> that will have a reference added.
    */
   [version=1.0]
   void AddRef([in] PP_Var var);
 
   /**
    * Release() removes a reference to given var, deleting it if the internal
-   * reference count becomes 0. If the given var is not a refcounted object,
-   * this function will do nothing so you can always call it no matter what
-   * the type.
+   * reference count becomes 0. If the <code>PP_Var</code> is of type
+   * <code>PP_VARTYPE_RESOURCE</code>,
+   * it will implicitly release a reference count on the
+   * <code>PP_Resource</code> (equivalent to PPB_Core::ReleaseResource()).
+   *
+   * If the given var is not a refcounted object, this function will do nothing
+   * so you can always call it no matter what the type.
    *
    * @param[in] var A <code>PP_Var</code> that will have a reference removed.
    */
   [version=1.0]
   void Release([in] PP_Var var);
 
   /**
    * VarFromUtf8() creates a string var from a string. The string must be
    * encoded in valid UTF-8 and is NOT NULL-terminated, the length must be
    * specified in <code>len</code>. It is an error if the string is not
    * valid UTF-8.
    *
    * If the length is 0, the <code>*data</code> pointer will not be dereferenced
    * and may be <code>NULL</code>. Note, however if length is 0, the
-   * "NULL-ness" will not be preserved, as <code>VarToUtf8</code> will never
+   * "NULL-ness" will not be preserved, as VarToUtf8() will never
    * return <code>NULL</code> on success, even for empty strings.
    *
    * The resulting object will be a refcounted string object. It will be
    * AddRef'ed for the caller. When the caller is done with it, it should be
    * Released.
    *
    * On error (basically out of memory to allocate the string, or input that
    * is not valid UTF-8), this function will return a Null var.
    *
    * @param[in] module A PP_Module uniquely identifying the module or .nexe.
    * @param[in] data A string
    * @param[in] len The length of the string.
    *
    * @return A <code>PP_Var</code> structure containing a reference counted
    * string object.
    */
   [version=1.0]
   PP_Var VarFromUtf8([in] PP_Module module, [in] str_t data, [in] uint32_t len);
 
   /**
    * VarFromUtf8() creates a string var from a string. The string must be
    * encoded in valid UTF-8 and is NOT NULL-terminated, the length must be
    * specified in <code>len</code>. It is an error if the string is not
    * valid UTF-8.
    *
    * If the length is 0, the <code>*data</code> pointer will not be dereferenced
    * and may be <code>NULL</code>. Note, however if length is 0, the
-   * "NULL-ness" will not be preserved, as <code>VarToUtf8</code> will never
-   * return <code>NULL</code> on success, even for empty strings.
+   * "NULL-ness" will not be preserved, as VarToUtf8() will never return
+   * <code>NULL</code> on success, even for empty strings.
    *
    * The resulting object will be a refcounted string object. It will be
    * AddRef'ed for the caller. When the caller is done with it, it should be
    * Released.
    *
    * On error (basically out of memory to allocate the string, or input that
    * is not valid UTF-8), this function will return a Null var.
    *
    * @param[in] data A string
    * @param[in] len The length of the string.
@@ skipping 31 matching lines @@
    * @param[in] var A <code>PP_Var</code> struct containing a resource-type var.
    *
    * @return A <code>PP_Resource</code> retrieved from the var, or 0 if the var
    * is not a resource. The reference count of the resource is incremented on
    * behalf of the caller.
    */
   [version=1.2]
   PP_Resource VarToResource([in] PP_Var var);
 
   /**
-   * Creates a new <code>PP_Var</code> from a given resource.
+   * Creates a new <code>PP_Var</code> from a given resource. Implicitly adds a
+   * reference count on the <code>PP_Resource</code> (equivalent to
+   * PPB_Core::AddRefResource(resource)).
    *
    * @param[in] resource A <code>PP_Resource</code> to be wrapped in a var.
    *
    * @return A <code>PP_Var</code> created for this resource, with type
    * <code>PP_VARTYPE_RESOURCE</code>. The reference count of the var is set to
    * 1 on behalf of the caller.
    */
   [version=1.2]
   PP_Var VarFromResource([in] PP_Resource resource);
 };