CharacterStyleData: Added some comments in the header

src/apps/haiku-depot/textview/CharacterStyleData.h

@@ -29,7 +29,10 @@ typedef BReference<CharacterStyleData>	CharacterStyleDataRef;
 
 
 // You cannot modify a CharacterStyleData object once it has been
-// created.
+// created. Instead, the setter methods return a new object that equals
+// the object on which the method has been called, except for the changed
+// property. If the property already has the requested value, then a
+// reference to the same object is returned.
 class CharacterStyleData : public BReferenceable {
 public:
 								CharacterStyleData();
@@ -46,9 +49,15 @@ public:
 									{ return fFont; }
 
 			CharacterStyleDataRef SetAscent(float ascent);
+			
+			// Returns the ascent of the configured font, unless the ascent
+			// has been overridden by a fixed value with SetAscent().
 			float				Ascent() const;
 
 			CharacterStyleDataRef SetDescent(float descent);
+
+			// Returns the descent of the configured font, unless the descent
+			// has been overridden by a fixed value with SetDescent().
 			float				Descent() const;
 
 			CharacterStyleDataRef SetWidth(float width);
@@ -90,14 +99,22 @@ private:
 			BFont				fFont;
 
 			// The following three values override glyph metrics unless -1
+			// This is useful when you want to have a place-holder character
+			// in the text. You would assign this character a CharacterStyle
+			// which defines ascent, descent and width to fixed values, thereby
+			// controlling the exact dimensions of the character, regardless of
+			// font size. Instead of the character, one could render an icon
+			// that is layouted within the text.
 			float				fAscent;
 			float				fDescent;
 			float				fWidth;
 
+			// Additional spacing to be applied between glyphs.
 			float				fGlyphSpacing;
 
 			rgb_color			fFgColor;
 			rgb_color			fBgColor;
+
 			rgb_color			fStrikeOutColor;
 			rgb_color			fUnderlineColor;