New CPP docs for mouse lock and fullscreen. The docs are identical to those found in the C IDL wi...

ppapi/cpp/fullscreen.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_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.

[yzshen1, 2011/12/21 23:04:14]

Comment like this (as well as the one for constructor) is of little use. I would
suggest to remove them.

[jond, 2012/01/03 17:48:28]

Yeah, I realize that, but I think for sake of having some documentation for
everything, it looks better to have a string than not. I can change these to
"empty destructor" or something else if you have a suggestion.

On 2011/12/21 23:04:14, yzshen1 wrote:

[yzshen1, 2012/01/03 18:06:26]

IMHO, I think it is the better to remove it.
The reason to just have some string for everything doesn't seem compelling.
On 2012/01/03 17:48:28, jond wrote:

   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>false</code> on success or <code>false</code> on

[yzshen1, 2011/12/21 23:04:14]

*true* on success

[jond, 2012/01/03 17:48:28]

Done.

+  /// failure.
   bool GetScreenSize(Size* size);
 
  private:
   Instance* instance_;
 };
 
 }  // namespace pp
 
 #endif  // PPAPI_CPP_FULLSCREEN_H_