Some description changes and documentation for logging.h

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

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

4 files changed, 28 insertions, 4 deletions

diff --git a/ppapi/cpp/input_event.h b/ppapi/cpp/input_event.h
index 81be497..195ac08 100644
--- a/ppapi/cpp/input_event.h
+++ b/ppapi/cpp/input_event.h
@@ -176,7 +176,7 @@ class WheelInputEvent : public InputEvent {
   /// is_null() or is not a wheel input event, the wheel object will be
   /// is_null().
   ///
-  /// @param[in] A generic input event.
+  /// @param[in] event A generic input event.
   explicit WheelInputEvent(const InputEvent& event);
 
   /// Constructs a wheel input even from the given parameters.
diff --git a/ppapi/cpp/instance.h b/ppapi/cpp/instance.h
index 528c08a..654aedbb 100644
--- a/ppapi/cpp/instance.h
+++ b/ppapi/cpp/instance.h
@@ -6,7 +6,7 @@
 #define PPAPI_CPP_INSTANCE_H_
 
 /// @file
-/// Defines the C++ wrapper for an instance.
+/// This file defines the C++ wrapper for an instance.
 
 #include <map>
 #include <string>
diff --git a/ppapi/cpp/logging.h b/ppapi/cpp/logging.h
index 42061c7..9e20f2e 100644
--- a/ppapi/cpp/logging.h
+++ b/ppapi/cpp/logging.h
@@ -1,14 +1,34 @@
-// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// 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_LOGGING_H_
 #define PPAPI_CPP_LOGGING_H_
 
+/// @file
+/// This file defines two macro asserts.
+
 #include <cassert>
 
+/// This macro asserts that 'a' evaluates to true. In debug mode, this macro
+/// will crash the program if the assertion evaluates to false. It (typically)
+/// has no effect in release mode.
 #define PP_DCHECK(a) assert(a)
 
+/// This macro asserts false in debug builds. It's used in code paths that you
+/// don't expect to execute.
+///
+/// <strong>Example:</code>
+///
+/// <code>
+/// if (!pointer) {
+/// // Pointer wasn't valid! This shouldn't happen.
+/// PP_NOTREACHED();
+/// return;
+/// }
+/// // Do stuff to the pointer, since you know it's valid.
+/// pointer->DoSomething();
+/// </code>
 #define PP_NOTREACHED() assert(false)
 
 #endif  // PPAPI_CPP_LOGGING_H_
diff --git a/ppapi/cpp/module_impl.h b/ppapi/cpp/module_impl.h
index e8d4fe7..fa2c619 100644
--- a/ppapi/cpp/module_impl.h
+++ b/ppapi/cpp/module_impl.h
@@ -1,10 +1,14 @@
-// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// 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_MODULE_IMPL_H_
 #define PPAPI_CPP_MODULE_IMPL_H_
 
+/// @file
+/// This file defines some simple function templates that help the C++ wrappers
+/// (and are not for external developers to use).
+
 #include "ppapi/cpp/module.h"
 
 namespace pp {