- * The third parameter is set to true only for a user defined macro, which
- * needs special handling. When it is a MathMacro, the needs_math_mode
- * parameter is true and the behavior is as in Example 1. When the
- * needs_math_mode parameter is false (not a MathMacro) and the macro
- * was entered in a text box and we are in math mode, the mode is reset
- * to text. This is because the macro was probably designed for text mode
- * (given that it was entered in text mode and we have no way to tell the
- * contrary).
+ * This form is mainly used for math macros as they are treated specially.
+ * In essence, the macros defined in the lib/symbols file and tagged as
+ * textmode will be enclosed in \lyxmathsym if they appear in a math mode
+ * environment, while macros defined in the preamble or ERT are left as is.
+ * The third parameter must be set to true and the fourth parameter has also
+ * to be specified. Only the following 3 different cases are handled.
+ *
+ * When the needs_mathmode parameter is true the behavior is as in Example 1.
+ * This is the case for a LyX InsetMathMacro or a macro not tagged as textmode.
+ *
+ * When the needs_mathmode and textmode_macro parameters are both false the
+ * macro is left in the same (text or math mode) environment it was entered.
+ * This is because it is assumed that the macro was designed for that mode
+ * and we have no way to tell the contrary.
+ * This is the case for macros defined by using \newcommand or \def in ERT.
+ *
+ * When the needs_mathmode parameter is false while textmode_macro is true the
+ * macro will be enclosed in \lyxmathsym if it appears in a math mode environment.
+ * This is the case for the macros tagged as textmode in lib/symbols.