Misc. changes. Mostly formatting.

ppapi/c/ppb_var.h

 /* Copyright (c) 2011 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.
  */
 #ifndef PPAPI_C_PPB_VAR_H_
 #define PPAPI_C_PPB_VAR_H_
 
 #include "ppapi/c/pp_bool.h"
 #include "ppapi/c/pp_instance.h"
 #include "ppapi/c/pp_macros.h"
 #include "ppapi/c/pp_module.h"
 #include "ppapi/c/pp_resource.h"
 #include "ppapi/c/pp_stdint.h"
 #include "ppapi/c/pp_var.h"
 
 #define PPB_VAR_INTERFACE_0_5 "PPB_Var;0.5"
 #define PPB_VAR_INTERFACE PPB_VAR_INTERFACE_0_5
 
 /**
  * @file
- * This file defines the PPB_Var struct.
+ * This file defines the <code>PPB_Var</code> struct.
  */
 
 /**
  * @addtogroup Interfaces
  * @{
  */
 
 /**
  * PPB_Var API
  */
 struct PPB_Var {
   /**
-   * Adds a reference to the given var. If this is not a refcounted object,
-   * this function will do nothing so you can always call it no matter what the
-   * type.
+   * AddRef() adds a reference to the given var. If this 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 added.
    */
   void (*AddRef)(struct PP_Var var);
 
   /**
-   * Removes a reference to given var, deleting it if the internal refcount
-   * 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.
+   * 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.
+   *
+   * @param[in] var A <code>PP_Var</code> that will have a reference removed.
    */
   void (*Release)(struct PP_Var var);
 
   /**
-   * 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 |len|.
-   * It is an error if the string is not valid UTF-8.
+   * 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 |data| pointer will not be dereferenced and may
-   * be NULL. Note, however, that if you do this, the "NULL-ness" will not be
-   * preserved, as VarToUtf8 will never return NULL on success, even for empty
-   * strings.
+   * 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.
    *
    * 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
-   * Release()d.
+   * 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.
    */
   struct PP_Var (*VarFromUtf8)(PP_Module module,
                                const char* data, uint32_t len);
 
   /**
-   * Converts a string-type var to a char* encoded in UTF-8. This string is NOT
-   * NULL-terminated. The length will be placed in |*len|. If the string is
-   * valid but empty the return value will be non-NULL, but |*len| will still
-   * be 0.
+   * VarToUtf8() converts a string-type var to a char* encoded in UTF-8. This
+   * string is NOT NULL-terminated. The length will be placed in
+   * <code>*len</code>. If the string is valid but empty the return value will
+   * be non-NULL, but <code>*len</code> will still be 0.
    *
-   * If the var is not a string, this function will return NULL and |*len| will
-   * be 0.
+   * If the var is not a string, this function will return NULL and
+   * <code>*len</code> will be 0.
    *
    * The returned buffer will be valid as long as the underlying var is alive.
-   * If the plugin frees its reference, the string will be freed and the pointer
+   * If the module frees its reference, the string will be freed and the pointer

[dmichael (off chromium), 2011/07/01 16:45:00]

module->instance

[jond, 2011/07/01 20:31:23]

Done.

    * will be to random memory.

[dmichael (off chromium), 2011/07/01 16:45:00]

random->arbitrary

[jond, 2011/07/01 20:31:23]

Done.

+   *
+   * @param[in] var A PP_Var struct containing a string-type var.
+   * @param[in,out] len A pointer to the length of the string-type var.
+   *
+   * @return A char* encoded in UTF-8.
    */
   const char* (*VarToUtf8)(struct PP_Var var, uint32_t* len);
 };
 /**
  * @}
  */
 
 #endif  /* PPAPI_C_PPB_VAR_H_ */