Add class level comments to ComputedStyle.

third_party/WebKit/Source/core/style/ComputedStyle.h

 /*
  * Copyright (C) 2000 Lars Knoll (knoll@kde.org)
  *           (C) 2000 Antti Koivisto (koivisto@kde.org)
  *           (C) 2000 Dirk Mueller (mueller@kde.org)
  * Copyright (C) 2003, 2005, 2006, 2007, 2008, 2009, 2010, 2011 Apple Inc. All
  * rights reserved.
  * Copyright (C) 2006 Graham Dennis (graham.dennis@gmail.com)
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Library General Public
@@ skipping 134 matching lines @@
 class StyleImage;
 class StylePath;
 class StyleResolver;
 class TransformationMatrix;
 class TranslateTransformOperation;
 
 class ContentData;
 
 typedef Vector<RefPtr<ComputedStyle>, 4> PseudoStyleCache;
 
-// ComputedStyle stores the final style for an element and provides the
-// interface between the style engine and the rest of Blink.
+// ComputedStyle stores the computed value [1] for every CSS property on an
+// element and provides the interface between the style engine and the rest of
+// Blink. It acts as a container where the computed value of every CSS property
+// can be stored and retrieved:
 //
-// It contains all the resolved styles for an element, and is densely packed and
-// optimized for memory and performance. Enums and small fields are packed in
-// bit fields, while large fields are stored in pointers and shared where not
-// modified from their parent value (see the DataRef class).
+//   auto style = ComputedStyle::Create();
+//   style->SetDisplay(EDisplay::kNone); //'display' keyword property
+//   style->Display();
 //
-// Currently, ComputedStyle is hand-written and ComputedStyleBase is generated.
-// Over time, methods will be moved to ComputedStyleBase and the generator will
-// be expanded to handle more and more types of properties. Eventually, all
-// methods will be on ComputedStyleBase (with custom methods defined in a class
-// such as ComputedStyleBase.cpp) and ComputedStyle will be removed.
+// In addition to storing the computed value of every CSS property,
+// ComputedStyle also contains various internal style information. Examples
+// include cached_pseudo_styles_ (for storing pseudo element styles), unique_
+// (for style sharing) and has_simple_underline_ (cached indicator flag of
+// text-decoration). These are stored on ComputedStyle for two reasons:
+//
+//  1) They share the same lifetime as ComputedStyle, so it is convenient to
+//  store them in the same object rather than a separate object that have to be
+//  passed around as well.
+//
+//  2) Many of these data members can be packed as bit fields, so we use less
+//  memory by packing them in this object with other bit fields.
+//
+// STORAGE:
+//
+// ComputedStyle is optimized for memory and performance. The data is not
+// actually stored directly in ComputedStyle, but rather in a generated parent
+// class ComputedStyleBase. This separation of concerns allows us to optimise
+// the memory layout without affecting users of ComputedStyle. ComputedStyle
+// inherits from ComputedStyleBase, which in turn takes ComputedStyle as a
+// template argument so that ComputedStyleBase can access methods declared on
+// ComputedStyle. For more about the memory layout, there is documentation in
+// ComputedStyleBase and make_computed_style_base.py.
+//
+// INTERFACE:
+//
+// For most CSS properties, ComputedStyle provides a consistent interface which
+// includes a getter, setter, initial method (the computed value when the
+// property is to 'initial'), and resetter (that resets the computed value to
+// its initial value). Exceptions include vertical-align, which has a separate
+// set of accessors for its length and its keyword components. Apart from
+// accessors, ComputedStyle also has a wealth of helper functions.
+//
+// Because ComputedStyleBase defines simple accessors to every CSS property,
+// ComputedStyle inherits these and so they are not redeclared in this file.
+// This means that the interface to ComputedStyle is split between this file and
+// ComputedStyleBase.h.
+//
+// [1] https://developer.mozilla.org/en-US/docs/Web/CSS/computed_value
+//
+// NOTE:
+//
+// Currently, some properties are stored in ComputedStyle and some in
+// ComputedStyleBase. Eventually, the storage of all properties (except SVG
+// ones) will be in ComputedStyleBase.
 class CORE_EXPORT ComputedStyle : public ComputedStyleBase<ComputedStyle>,
                                   public RefCounted<ComputedStyle> {
   // Used by Web Animations CSS. Sets the color styles.
   friend class AnimatedStyleBuilder;
   // Used by Web Animations CSS. Gets visited and unvisited colors separately.
   friend class CSSAnimatableValueFactory;
   // Used by CSS animations. We can't allow them to animate based off visited
   // colors.
   friend class CSSPropertyEquality;
   // Editing has to only reveal unvisited info.
@@ skipping 3567 matching lines @@
       PseudoBitsInternal() | 1 << (pseudo - kFirstPublicPseudoId)));
 }
 
 inline bool ComputedStyle::HasPseudoElementStyle() const {
   return PseudoBitsInternal() & kElementPseudoIdMask;
 }
 
 }  // namespace blink
 
 #endif  // ComputedStyle_h