Addressing Mads' comments from http://codereview.chromium.org/3585010/show.

include/v8.h

 // Copyright 2007-2009 the V8 project authors. All rights reserved.
 // Redistribution and use in source and binary forms, with or without
 // modification, are permitted provided that the following conditions are
 // met:
 //
 //     * Redistributions of source code must retain the above copyright
 //       notice, this list of conditions and the following disclaimer.
 //     * Redistributions in binary form must reproduce the above
 //       copyright notice, this list of conditions and the following
 //       disclaimer in the documentation and/or other materials provided
@@ skipping 1354 matching lines @@
  private:
   V8EXPORT static void CheckCast(v8::Value* obj);
 };
 
 
 /**
  * An instance of the built-in RegExp constructor (ECMA-262, 15.10).
  */
 class RegExp : public Value {
  public:
+  /**
+   * Regular expression flag bits. They can be or'ed to enable a set
+   * of flags.
+   */
   enum Flags {
     kNone = 0,
     kGlobal = 1,
     kIgnoreCase = 2,
     kMultiline = 4
   };
 
+  /**
+   * Creates a regular expression from the given pattern string and
+   * the flags bit field. May throw a JavaScript exception as
+   * described in ECMA-252, 15.10.4.1.
+   *
+   * For example,
+   *   RegExp::New(v8::String::New("foo"),
+   *               static_cast<RegExp::Flags>(kGlobal | kMultiline))
+   * is equivalent to evaluating "/foo/gm".
+   */
   V8EXPORT static Local<RegExp> New(Handle<String> pattern,
                                     Flags flags);
 
   /**
    * Returns the value of the source property: a string representing
    * the regular expression.
    */
   V8EXPORT Local<String> GetSource() const;
 
+  /**
+   * Returns the flags bit field.
+   */
   V8EXPORT Flags GetFlags() const;
 
   static inline RegExp* Cast(v8::Value* obj);
 
  private:
   V8EXPORT static void CheckCast(v8::Value* obj);
 };
 
 
 enum PropertyAttribute {
@@ skipping 2322 matching lines @@
 
 
 }  // namespace v8
 
 
 #undef V8EXPORT
 #undef TYPE_CHECK
 
 
 #endif  // V8_H_