Missed some items to document here. New documentation.

Review URL: http://codereview.chromium.org/7621019

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@96987 0039d316-1c4b-4281-b951-d872f2087c98

ppapi/cpp/module.h

@@ -36,72 +36,109 @@ class Module {
   Module();
   virtual ~Module();
 
-  // Returns the global instance of this module object, or NULL if the module
-  // is not initialized yet.
+  /// Get() returns the global instance of this module object, or NULL if the
+  /// module is not initialized yet.
+  ///
+  /// @return The global instance of the module object.
   static Module* Get();
 
-  // This function will be automatically called after the object is created.
-  // This is where you can put functions that rely on other parts of the API,
-  // now that the module has been created.
+  /// Init() is automatically called after the object is created. This is where
+  /// you can put functions that rely on other parts of the API, now that the
+  /// module has been created.
+  ///
+  /// @return true if successful, otherwise false.
   virtual bool Init();
 
-  // Returns the internal module handle.
+  /// The pp_module() function returns the internal module handle.
+  ///
+  /// @return A <code>PP_Module</code> internal module handle.
   PP_Module pp_module() const { return pp_module_; }
 
-  // Returns the internal get_browser_interface pointer.
-  // TODO(sehr): This should be removed once the NaCl browser plugin no longer
-  // needs it.
+  /// The get_browser_interface() function returns the internal
+  /// <code>get_browser_interface</code> pointer.
+  /// TODO(sehr): This should be removed once the NaCl browser plugin no longer
+  /// needs it.
+  ///
+  /// @return A <code>PPB_GetInterface</code> internal pointer.
   PPB_GetInterface get_browser_interface() const {
     return get_browser_interface_;
   }
 
-  // Returns the core interface for doing basic global operations. This is
-  // guaranteed to be non-NULL once the module has successfully initialized
-  // and during the Init() call.
-  //
-  // It will be NULL before Init() has been called.
+  /// The core() function returns the core interface for doing basic
+  /// global operations. The return value is guaranteed to be non-NULL once the
+  /// module has successfully initialized and during the Init() call.
+  ///
+  /// It will be NULL before Init() has been called.
+  ///
+  /// @return The core interface for doing basic global operations.
   Core* core() { return core_; }
 
-  // Implements GetInterface for the browser to get plugin interfaces. If you
-  // need to provide your own implementations of new interfaces, you can use
-  // AddPluginInterface which this function will use.
+  /// GetPluginInterface() implements <code>GetInterface</code> for the browser
+  /// to get module interfaces. If you need to provide your own implementations
+  /// of new interfaces, use AddPluginInterface() which this function will use.
+  ///
+  /// @param[in] interface_name The module interface for the browser to get.
   const void* GetPluginInterface(const char* interface_name);
 
-  // Returns an interface in the browser.
+  /// GetBrowserInterface() returns interfaces which the browser implements
+  /// (i.e. PPB interfaces).
+  /// @param[in] interface_name The browser interface for the moduel to get.
   const void* GetBrowserInterface(const char* interface_name);
 
-  // Returns the object associated with this PP_Instance, or NULL if one is
-  // not found.
+  /// InstanceForPPInstance() returns the object associated with this
+  /// <code>PP_Instance</code>, or NULL if one is not found.
+  ///
+  /// @param[in] instance This <code>PP_Instance</code>.
+  ///
+  /// @return The object associated with this <code>PP_Instance</code>,
+  /// or NULL if one is not found.
   Instance* InstanceForPPInstance(PP_Instance instance);
 
-  // Adds a handler for a given interface name. When the browser requests
-  // that interface name, the given |vtable| will be returned.
-  //
-  // In general, plugins will not need to call this directly. Instead, the
-  // C++ wrappers for each interface will register themselves with this
-  // function.
-  //
-  // This function may be called more than once with the same interface name
-  // and vtable with no effect. However, it may not be used to register a
-  // different vtable for an already-registered interface. It will assert for
-  // a different registration for an already-registered interface in debug
-  // mode, and just ignore the registration in release mode.
+  /// AddPluginInterface() adds a handler for a provided interface name. When
+  /// the browser requests that interface name, the provided
+  /// <code>vtable</code> will be returned.
+  ///
+  /// In general, modules will not need to call this directly. Instead, the
+  /// C++ wrappers for each interface will register themselves with this
+  /// function.
+  ///
+  /// This function may be called more than once with the same interface name
+  /// and vtable with no effect. However, it may not be used to register a
+  /// different vtable for an already-registered interface. It will assert for
+  /// a different registration for an already-registered interface in debug
+  /// mode, and just ignore the registration in release mode.
+  ///
+  /// @param[in] interface_name The interface name that will receive a handler.
+  /// @param[in,out] vtable The vtable to return for
+  /// <code>interface_name</code>.
   void AddPluginInterface(const std::string& interface_name,
                           const void* vtable);
 
-  // Sets the browser interface and calls the regular init function that
-  // can be overridden by the base classes.
-  //
-  // TODO(brettw) make this private when I can figure out how to make the
-  // initialize function a friend.
+  // InternalInit() sets the browser interface and calls the regular Init()
+  /// function that can be overridden by the base classes.
+  ///
+  /// TODO(brettw) make this private when I can figure out how to make the
+  /// initialize function a friend.
+  ///
+  /// @param[in] mod A <code>PP_Module</code>.
+  /// @param[in] get_browser_interface The browser interface to set.
+  ///
+  /// @return true if successful, otherwise false.
   bool InternalInit(PP_Module mod,
                     PPB_GetInterface get_browser_interface);
 
-  // Allows iteration over the current instances in the module.
+  /// The current_instances() function allows iteration over the
+  /// current instances in the module.
+  ///
+  /// @return An <code>InstanceMap</code> of all instances in the module.
   const InstanceMap& current_instances() const { return current_instances_; }
 
  protected:
-  // Override to create your own plugin type.
+  /// CreateInstance() should be overridden to create your own module type.
+  ///
+  /// @param[in] instance A <code>PP_Instance</code>.
+  ///
+  /// @return The resulting instance.
   virtual Instance* CreateInstance(PP_Instance instance) = 0;
 
  private: