document docstring abuse for symbol font code points

git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@15791 a592a061-630c-0410-9148-cb99ea01b6c8

src/frontends/FontMetrics.h

@@ -38,6 +38,11 @@
  *               <-  width ->
  * --------------+----------+-------<maxDescent
  *
+ * Caution: All char_type and docstring arguments of any method of this class
+ * are no UCS4 chars or strings if the font is a symbol font. They simply
+ * denote the code points of the font instead. You have to keep this in mind
+ * when you implement the methods in a frontend. You must not pass these
+ * parameters to a unicode conversion function in particular.
  */
 
 namespace lyx {

src/frontends/Painter.h

@@ -43,6 +43,13 @@ namespace frontend {
  * management.
  *
  * Note that the methods return *this for convenience.
+ *
+ * Caution: All char_type and docstring arguments of the text drawing
+ * methods of this class are no UCS4 chars or strings if the font is a
+ * symbol font. They simply denote the code points of the font instead.
+ * You have to keep this in mind when you implement the methods in a
+ * frontend. You must not pass these parameters to a unicode conversion
+ * function in particular.
  */
 class Painter {
 public:

src/frontends/qt4/GuiFontMetrics.C

@@ -105,6 +105,10 @@ int GuiFontMetrics::smallcapsWidth(QString const & s) const
 
 int GuiFontMetrics::width(char_type const * s, size_t ls) const
 {
+	// Caution: The following ucs4_to_something conversions work for
+	// symbol fonts only because they are no real conversions but simple
+	// casts in reality.
+
 	if (ls == 1 && !smallcaps_shape_) {
 		QChar const c = ucs4_to_qchar(s[0]);
 		return width(c.unicode());

src/frontends/qt4/QLPainter.C

@@ -211,6 +211,10 @@ int QLPainter::smallCapsText(int x, int y,
 int QLPainter::text(int x, int y, char_type const * s, size_t ls,
 	LyXFont const & f)
 {
+	// Caution: The following ucs4_to_qstring conversion works for
+	// symbol fonts only because it is no real conversion but a simple
+	// cast in reality.
+
 	QString str;
 	ucs4_to_qstring(s, ls, str);
 

src/mathed/MathParser.h

@@ -35,11 +35,23 @@ public:
 	docstring name;
 	/// name of a inset that handles that macro
 	docstring inset;
-	/// position of the thing in a font	
+	/**
+	 * The string or symbol to draw.
+	 * This is a string of length 1 if \p name is a known symbol, and
+	 * the corresponding font is available. In this case it is
+	 * NO UCS4 STRING! The only "character" of the string simply denotes
+	 * the code point of the symbol in the font. Therefore you have to
+	 * be very careful if you pass \c draw to any function that takes a
+	 * docstring argument.
+	 * If \p name is a known symbol, but the corresponding font is not
+	 * available, or if it is a function name, then \c draw contains a
+	 * regular UCS4 string (actuallay \c draw == \c name) that is painted
+	 * on screen.
+	 */
 	docstring draw;
 	/// operator/..., fontname e
 	docstring extra;
-	/// how is this called as XML entity?
+	/// how is this called as XML entity in MathML?
 	docstring xmlname;
 	/// required LaTeXFeatures
 	docstring requires;