New CPP docs for mouse lock and fullscreen. The docs are identical to those found in the C IDL with the exception of class descriptions and a CPP-specific types

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

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

2 files changed, 112 insertions, 28 deletions

diff --git a/ppapi/cpp/fullscreen.h b/ppapi/cpp/fullscreen.h
index cb6a4f3..18ae43d 100644
--- a/ppapi/cpp/fullscreen.h
+++ b/ppapi/cpp/fullscreen.h
@@ -1,23 +1,65 @@
-// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// 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.
 
 #ifndef PPAPI_CPP_FULLSCREEN_H_
 #define PPAPI_CPP_FULLSCREEN_H_
 
+/// @file
+/// This file defines the API for handling transitions of a module instance to
+/// and from fullscreen mode.
+
 namespace pp {
 
 class Instance;
 class Size;
 
+/// The Fullscreen class allowing you to check and toggle fullscreen mode.
 class Fullscreen {
  public:
+  /// A constructor for creating a <code>Fullscreen</code>.
+  ///
+  /// @param[in] instance The instance that will own the new
+  /// <code>Fullscreen</code>.
   Fullscreen(Instance* instance);
+
+  /// Destructor.
   virtual ~Fullscreen();
 
-  // PPB_Fullscreen methods.
+  /// IsFullscreen() checks whether the module instance is currently in
+  /// fullscreen mode.
+  ///
+  /// @return <code>true</code> if the module instance is in fullscreen mode,
+  ///<code>false</code> if the module instance is not in fullscreen mode.
   bool IsFullscreen();
+
+  /// SetFullscreen() switches the module instance to and from fullscreen
+  /// mode.
+  ///
+  /// The transition to and from fullscreen mode is asynchronous. During the
+  /// transition, IsFullscreen() will return the previous value and
+  /// no 2D or 3D device can be bound. The transition ends at DidChangeView()
+  /// when IsFullscreen() returns the new value. You might receive other
+  /// DidChangeView() calls while in transition.
+  ///
+  /// The transition to fullscreen mode can only occur while the browser is
+  /// processing a user gesture, even if <code>true</code> is returned.
+  ///
+  /// @param[in] fullscreen <code>true</code> to enter fullscreen mode, or
+  /// <code>false</code> to exit fullscreen mode.
+  ///
+  ///@return <code>true</code> on success or <code>false</code> on
+  /// failure.
   bool SetFullscreen(bool fullscreen);
+
+  /// GetScreenSize() gets the size of the screen in pixels. The module instance
+  /// will be resized to this size when SetFullscreen() is called to enter
+  /// fullscreen mode.
+  ///
+  /// @param[out] size The size of the entire screen in pixels.
+  ///
+  /// @return <code>true</code> on success or <code>false</code> on
+  /// failure.
   bool GetScreenSize(Size* size);
 
  private:
diff --git a/ppapi/cpp/mouse_lock.h b/ppapi/cpp/mouse_lock.h
index b04c07c..69533f1f 100644
--- a/ppapi/cpp/mouse_lock.h
+++ b/ppapi/cpp/mouse_lock.h
@@ -1,4 +1,4 @@
-// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// 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.
 
@@ -7,44 +7,86 @@
 
 #include "ppapi/c/pp_stdint.h"
 
+/// @file
+/// This file defines the API for locking the target of mouse events to a
+/// specific module instance.
+
 namespace pp {
 
 class CompletionCallback;
 class Instance;
 
-// This class allows you to associate the PPP_MouseLock and PPB_MouseLock
-// C-based interfaces with an object. It associates itself with the given
-// instance, and registers as the global handler for handling the PPP_MouseLock
-// interface that the browser calls.
-//
-// You would typically use this either via inheritance on your instance:
-//   class MyInstance : public pp::Instance, public pp::MouseLock {
-//     class MyInstance() : pp::MouseLock(this) {
-//     }
-//     ...
-//   };
-//
-// or by composition:
-//   class MyMouseLock : public pp::MouseLock {
-//     ...
-//   };
-//
-//   class MyInstance : public pp::Instance {
-//     MyInstance() : mouse_lock_(this) {
-//     }
-//
-//     MyMouseLock mouse_lock_;
-//   };
+/// This class allows you to associate the <codee>PPP_MouseLock</code> and
+/// <code>PPB_MouseLock</code> C-based interfaces with an object. It associates
+/// itself with the given instance, and registers as the global handler for
+/// handling the <code>PPP_MouseLock</code> interface that the browser calls.
+///
+/// You would typically use this class by inheritance on your instance or by
+/// composition.
+///
+/// <strong>Example (inheritance):</strong>
+/// <code>
+///   class MyInstance : public pp::Instance, public pp::MouseLock {
+///     class MyInstance() : pp::MouseLock(this) {
+///     }
+///     ...
+///   };
+/// </code>
+///
+/// <strong>Example (composition):</strong>
+/// <code>
+///   class MyMouseLock : public pp::MouseLock {
+///     ...
+///   };
+///
+///   class MyInstance : public pp::Instance {
+///     MyInstance() : mouse_lock_(this) {
+///     }
+///
+///     MyMouseLock mouse_lock_;
+///   };
+/// </code>
 class MouseLock {
  public:
+  /// A constructor for creating a <code>MouseLock</code>.
+  ///
+  /// @param[in] instance The instance that will own the new
+  /// <code>MouseLock</code>.
   explicit MouseLock(Instance* instance);
+
+  /// Destructor.
   virtual ~MouseLock();
 
-  // PPP_MouseLock functions exposed as virtual functions for you to override.
+  /// PPP_MouseLock functions exposed as virtual functions for you to override.
   virtual void MouseLockLost() = 0;
 
-  // PPB_MouseLock functions for you to call.
+  /// LockMouse() requests the mouse to be locked. The browser will permit
+  /// mouse lock only while the tab is in fullscreen mode.
+  ///
+  /// While the mouse is locked, the cursor is implicitly hidden from the user.
+  /// Any movement of the mouse will generate a
+  /// <code>PP_INPUTEVENT_TYPE_MOUSEMOVE</code> event. The
+  /// <code>GetPosition()</code> function in <code>InputEvent()</code>
+  /// reports the last known mouse position just as mouse lock was
+  /// entered. The <code>GetMovement()</code> function provides relative
+  /// movement information indicating what the change in position of the mouse
+  /// would be had it not been locked.
+  ///
+  /// The browser may revoke the mouse lock for reasons including (but not
+  /// limited to) the user pressing the ESC key, the user activating another
+  /// program using a reserved keystroke (e.g. ALT+TAB), or some other system
+  /// event.
+  ///
+  /// @param[in] callback A <code>PP_CompletionCallback</code> to be called upon
+  /// completion.
+  ///
+  /// @return An int32_t containing an error code from <code>pp_errors.h</code>.
   int32_t LockMouse(const CompletionCallback& cc);
+
+  /// UnlockMouse causes the mouse to be unlocked, allowing it to track user
+  /// movement again. This is an asynchronous operation. The module instance
+  /// will be notified using the <code>PPP_MouseLock</code> interface when it
+  /// has lost the mouse lock.
   void UnlockMouse();
 
  private: