Using comments in lexer code to document meaning of properties.

Automatically extract into SciTE doumentation.

7 files changed, 86 insertions, 0 deletions

diff --git a/src/LexCPP.cxx b/src/LexCPP.cxx
index d12a6e0db..9a8d49bb6 100644
--- a/src/LexCPP.cxx
+++ b/src/LexCPP.cxx
@@ -58,6 +58,9 @@ static void ColouriseCppDoc(unsigned int startPos, int length, int initStyle, Wo
 	WordList &keywords3 = *keywordlists[2];
 	WordList &keywords4 = *keywordlists[3];
 
+	// property styling.within.preprocessor
+	//	For C++ code, determines whether all preprocessor code is styled in the preprocessor style (0, the default) 
+	//	or only from the initial # to the end of the command word(1). 
 	bool stylingWithinPreprocessor = styler.GetPropertyInt("styling.within.preprocessor") != 0;
 
 	CharacterSet setOKBeforeRE(CharacterSet::setNone, "([{=,:;!%^&*|?~+-");
@@ -67,6 +70,9 @@ static void ColouriseCppDoc(unsigned int startPos, int length, int initStyle, Wo
 
 	CharacterSet setWordStart(CharacterSet::setAlpha, "_", 0x80, true);
 	CharacterSet setWord(CharacterSet::setAlphaNum, "._", 0x80, true);
+
+	// property lexer.cpp.allow.dollars
+	//	Set to 0 to disallow the '$' character in identifiers with the cpp lexer. 
 	if (styler.GetPropertyInt("lexer.cpp.allow.dollars", 1) != 0) {
 		setWordStart.Add('$');
 		setWord.Add('$');
@@ -371,10 +377,24 @@ static bool IsStreamCommentStyle(int style) {
 // and to make it possible to fiddle the current level for "} else {".
 static void FoldCppDoc(unsigned int startPos, int length, int initStyle,
 					   WordList *[], Accessor &styler) {
+
+	// property fold.comment
+	//	This option enables folding multi-line comments and explicit fold points when using the C++ lexer. 
+	//	Explicit fold points allows adding extra folding by placing a //{ comment at the start and a //} 
+	//	at the end of a section that should fold. 
 	bool foldComment = styler.GetPropertyInt("fold.comment") != 0;
+
+	// property fold.preprocessor
+	//	This option enables folding preprocessor directives when using the C++ lexer. 
+	//	Includes C#'s explicit #region and #endregion folding directives. 
 	bool foldPreprocessor = styler.GetPropertyInt("fold.preprocessor") != 0;
+
 	bool foldCompact = styler.GetPropertyInt("fold.compact", 1) != 0;
+
+	// property fold.at.else 
+	//	This option enables C++ folding on a "} else {" line of an if statement. 
 	bool foldAtElse = styler.GetPropertyInt("fold.at.else", 0) != 0;
+
 	unsigned int endPos = startPos + length;
 	int visibleChars = 0;
 	int lineCurrent = styler.GetLine(startPos);
diff --git a/src/LexD.cxx b/src/LexD.cxx
index 95be129d5..850642111 100644
--- a/src/LexD.cxx
+++ b/src/LexD.cxx
@@ -268,6 +268,9 @@ static bool IsStreamCommentStyle(int style) {
 static void FoldDoc(unsigned int startPos, int length, int initStyle, Accessor &styler) {
     bool foldComment = styler.GetPropertyInt("fold.comment") != 0;
     bool foldCompact = styler.GetPropertyInt("fold.compact", 1) != 0;
+
+    // property lexer.d.fold.at.else 
+    //	This option enables D folding on a "} else {" line of an if statement. 
     bool foldAtElse = styler.GetPropertyInt("lexer.d.fold.at.else",
 		styler.GetPropertyInt("fold.at.else", 0)) != 0;
     unsigned int endPos = startPos + length;
diff --git a/src/LexHTML.cxx b/src/LexHTML.cxx
index c244dff27..99afa2309 100644
--- a/src/LexHTML.cxx
+++ b/src/LexHTML.cxx
@@ -574,6 +574,10 @@ static void ColouriseHyperTextDoc(unsigned int startPos, int length, int initSty
 	} else {
 		// Default client and ASP scripting language is JavaScript
 		lineState = eScriptJS << 8;
+
+		// property asp.default.language 
+		//	Script in ASP code is initially assumed to be in JavaScript. 
+		//	To change this to VBScript set asp.default.language to 2. Python is 3.
 		lineState |= styler.GetPropertyInt("asp.default.language", eScriptJS) << 4;
 	}
 	script_mode inScriptType = script_mode((lineState >> 0) & 0x03); // 2 bits of scripting mode
@@ -590,13 +594,37 @@ static void ColouriseHyperTextDoc(unsigned int startPos, int length, int initSty
 		scriptLanguage = eScriptComment;
 	}
 
+	// property fold.html 
+	//	Folding is turned on or off for HTML and XML files with this option. 
+	//	The fold option must also be on for folding to occur.
 	const bool foldHTML = styler.GetPropertyInt("fold.html", 0) != 0;
+
 	const bool fold = foldHTML && styler.GetPropertyInt("fold", 0);
+
+	// property fold.html.preprocessor 
+	//	Folding is turned on or off for scripts embedded in HTML files with this option. 
+	//	The default is on.
 	const bool foldHTMLPreprocessor = foldHTML && styler.GetPropertyInt("fold.html.preprocessor", 1);
+
 	const bool foldCompact = styler.GetPropertyInt("fold.compact", 1) != 0;
+
+	// property fold.hypertext.comment 
+	//	Allow folding for comments in scripts embedded in HTML. 
+	//	The default is off. 
 	const bool foldComment = fold && styler.GetPropertyInt("fold.hypertext.comment", 0) != 0;
+
+	// property fold.hypertext.heredoc 
+	//	Allow folding for heredocs in scripts embedded in HTML. 
+	//	The default is off.  
 	const bool foldHeredoc = fold && styler.GetPropertyInt("fold.hypertext.heredoc", 0) != 0;
+
+	// property html.tags.case.sensitive 
+	//	For XML and HTML, setting this property to 1 will make tags match in a case 
+	//	sensitive way which is the expected behaviour for XML and XHTML. 
 	const bool caseSensitive = styler.GetPropertyInt("html.tags.case.sensitive", 0) != 0;
+
+	// property lexer.xml.allow.scripts 
+	//	Set to 0 to disable scripts in XML.  
 	const bool allowScripts = styler.GetPropertyInt("lexer.xml.allow.scripts", 1) != 0;
 
 	const CharacterSet setHTMLWord(CharacterSet::setAlphaNum, ".-_:!#", 0x80, true);
diff --git a/src/LexOthers.cxx b/src/LexOthers.cxx
index f5382bfdc..3c6940bfc 100644
--- a/src/LexOthers.cxx
+++ b/src/LexOthers.cxx
@@ -694,6 +694,11 @@ static void ColourisePropsDoc(unsigned int startPos, int length, int, WordList *
 	styler.StartSegment(startPos);
 	unsigned int linePos = 0;
 	unsigned int startLine = startPos;
+
+	// property lexer.props.allow.initial.spaces 
+	//	For properties files, set to 0 to style all lines that start with whitespace in the default style. 
+	//	This is not suitable for SciTE .properties files which use indentation for flow control but 
+	//	can be used for RFC2822 text where indentation is used for continuation lines. 
 	bool allowInitialSpaces = styler.GetPropertyInt("lexer.props.allow.initial.spaces", 1) != 0;
 
 	for (unsigned int i = startPos; i < startPos + length; i++) {
@@ -1097,6 +1102,12 @@ static void ColouriseErrorListDoc(unsigned int startPos, int length, int, WordLi
 	styler.StartAt(startPos);
 	styler.StartSegment(startPos);
 	unsigned int linePos = 0;
+
+	// property lexer.errorlist.value.separate 
+	//	For lines in the output pane that are matches from Find in Files or GCC-style 
+	//	diagnostics, style the path and line number separately from the rest of the 
+	//	line with style 21 used for the rest of the line. 
+	//	This allows matched text to be more easily distinguished from its location. 
 	bool valueSeparate = styler.GetPropertyInt("lexer.errorlist.value.separate", 0) != 0;
 	for (unsigned int i = startPos; i < startPos + length; i++) {
 		lineBuffer[linePos++] = styler[i];
diff --git a/src/LexPerl.cxx b/src/LexPerl.cxx
index 4853460bf..22b455d0e 100644
--- a/src/LexPerl.cxx
+++ b/src/LexPerl.cxx
@@ -1184,8 +1184,15 @@ static void FoldPerlDoc(unsigned int startPos, int length, int, WordList *[],
 	bool foldComment = styler.GetPropertyInt("fold.comment") != 0;
 	bool foldCompact = styler.GetPropertyInt("fold.compact", 1) != 0;
 	// Custom folding of POD and packages
+
+	// property fold.perl.pod 
+	//	Enable folding Pod blocks when using the Perl lexer. 
 	bool foldPOD = styler.GetPropertyInt("fold.perl.pod", 1) != 0;
+
+	// property fold.perl.package 
+	//	Enable folding packages when using the Perl lexer. 
 	bool foldPackage = styler.GetPropertyInt("fold.perl.package", 1) != 0;
+
 	unsigned int endPos = startPos + length;
 	int visibleChars = 0;
 	int lineCurrent = styler.GetLine(startPos);
diff --git a/src/LexPython.cxx b/src/LexPython.cxx
index 4513dccf2..26b96e4db 100644
--- a/src/LexPython.cxx
+++ b/src/LexPython.cxx
@@ -135,6 +135,14 @@ static void ColourisePyDoc(unsigned int startPos, int length, int initStyle,
 	WordList &keywords = *keywordlists[0];
 	WordList &keywords2 = *keywordlists[1];
 
+	// property tab.timmy.whinge.level
+	//	For Python code, checks whether indenting is consistent. 
+	//	The default, 0 turns off indentation checking, 
+	//	1 checks whether each line is potentially inconsistent with the previous line, 
+	//	2 checks whether any space characters occur before a tab character in the indentation, 
+	//	3 checks whether any spaces are in the indentation, and 
+	//	4 checks for any tab characters in the indentation.
+	//	1 is a good level to use. 
 	const int whingeLevel = styler.GetPropertyInt("tab.timmy.whinge.level");
 
 	// property lexer.python.literals.binary
@@ -399,7 +407,13 @@ static void FoldPyDoc(unsigned int startPos, int length, int /*initStyle - unuse
 	const int maxPos = startPos + length;
 	const int maxLines = styler.GetLine(maxPos - 1);             // Requested last line
 	const int docLines = styler.GetLine(styler.Length() - 1);  // Available last line
+
+	// property fold.comment.python
+	//	This option enables folding multi-line comments when using the Python lexer.
 	const bool foldComment = styler.GetPropertyInt("fold.comment.python") != 0;
+
+	// property fold.quotes.python
+	//	This option enables folding multi-line quoted strings when using the Python lexer.
 	const bool foldQuotes = styler.GetPropertyInt("fold.quotes.python") != 0;
 
 	// Backtrack to previous non-blank line so we can determine indent level
diff --git a/src/LexSQL.cxx b/src/LexSQL.cxx
index eb1cddbdf..01aa7ad0f 100644
--- a/src/LexSQL.cxx
+++ b/src/LexSQL.cxx
@@ -61,7 +61,10 @@ static void ColouriseSQLDoc(unsigned int startPos, int length, int initStyle, Wo
 
 	StyleContext sc(startPos, length, initStyle, styler);
 
+	// property sql.backslash.escapes 
+	//	Enables backslash as an escape character in SQL. 
 	bool sqlBackslashEscapes = styler.GetPropertyInt("sql.backslash.escapes", 0) != 0;
+
 	bool sqlBackticksIdentifier = styler.GetPropertyInt("lexer.sql.backticks.identifier", 0) != 0;
 	int styleBeforeDCKeyword = SCE_SQL_DEFAULT;
 	for (; sc.More(); sc.Forward()) {