Updated documentation comments from Philippe.

29 files changed, 269 insertions, 138 deletions

diff --git a/src/AutoComplete.cxx b/src/AutoComplete.cxx
index 1a4e15021..6abae23d6 100644
--- a/src/AutoComplete.cxx
+++ b/src/AutoComplete.cxx
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// AutoComplete.cxx - defines the auto completion list box
+/** @file AutoComplete.cxx
+ ** Defines the auto completion list box.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/AutoComplete.h b/src/AutoComplete.h
index df7006301..294b58bd6 100644
--- a/src/AutoComplete.h
+++ b/src/AutoComplete.h
@@ -1,56 +1,61 @@
 // Scintilla source code edit control
-// AutoComplete.h - defines the auto completion list box
+/** @file AutoComplete.h
+ ** Defines the auto completion list box.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
 #ifndef AUTOCOMPLETE_H
 #define AUTOCOMPLETE_H
 
+/**
+ */
 class AutoComplete {
 	bool active;
 	char stopChars[256];
 	char fillUpChars[256];
 	char separator;
+
 public:
 	bool ignoreCase;
 	bool chooseSingle;
 	ListBox lb;
 	int posStart;
 	int startLen;
-	// Should autocompletion be canceled if editor's currentPos <= startPos?
+	/// Should autocompletion be canceled if editor's currentPos <= startPos?
 	bool cancelAtStartPos;
 	
 	AutoComplete();
 	~AutoComplete();
 
-	// Is the auto completion list displayed?	
+	/// Is the auto completion list displayed?
 	bool Active();
 	
-	// Display the auto completion list positioned to be near a character position
+	/// Display the auto completion list positioned to be near a character position
 	void Start(Window &parent, int ctrlID, int position, int startLen_);
 	
-	// The stop chars are characters which, when typed, cause the auto completion list to disappear
+	/// The stop chars are characters which, when typed, cause the auto completion list to disappear
 	void SetStopChars(const char *stopChars_);
 	bool IsStopChar(char ch);
 	
-	// The fillup chars are characters which, when typed, fill up the selected word
+	/// The fillup chars are characters which, when typed, fill up the selected word
 	void SetFillUpChars(const char *fillUpChars_);
 	bool IsFillUpChar(char ch);
 
-	// The separator character is used when interpreting the list in SetList
+	/// The separator character is used when interpreting the list in SetList
 	void SetSeparator(char separator_);
 	char GetSeparator();
 	
-	// The list string contains a sequence of words separated by the separator character
+	/// The list string contains a sequence of words separated by the separator character
 	void SetList(const char *list);
 	
 	void Show();
 	void Cancel();
 	
-	// Move the current list element by delta, scrolling appropriately
+	/// Move the current list element by delta, scrolling appropriately
 	void Move(int delta);
 	
-	// Select a list element that starts with word as the current element
+	/// Select a list element that starts with word as the current element
 	void Select(const char *word);
 };
 
diff --git a/src/CallTip.cxx b/src/CallTip.cxx
index da6c6a06d..3483f89c1 100644
--- a/src/CallTip.cxx
+++ b/src/CallTip.cxx
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// CallTip.cxx - code for displaying call tips
+/** @file CallTip.cxx
+ ** Code for displaying call tips.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/CallTip.h b/src/CallTip.h
index c30c8f3b8..b38a4840a 100644
--- a/src/CallTip.h
+++ b/src/CallTip.h
@@ -1,11 +1,15 @@
 // Scintilla source code edit control
-// CallTip.h - interface to the call tip control
+/** @file CallTip.h
+ ** Interface to the call tip control.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
 #ifndef CALLTIP_H
 #define CALLTIP_H
 
+/**
+ */
 class CallTip {
 	int startHighlight;
 	int endHighlight;
@@ -14,6 +18,7 @@ class CallTip {
 	// Private so CallTip objects can not be copied
 	CallTip(const CallTip &) {}
 	CallTip &operator=(const CallTip &) { return *this; }
+
 public:
 	Window wCallTip;
 	Window wDraw;
@@ -28,19 +33,19 @@ public:
 	CallTip();
 	~CallTip();
 	
-	// Claim or accept palette entries for the colours required to paint a calltip
+	/// Claim or accept palette entries for the colours required to paint a calltip.
 	void RefreshColourPalette(Palette &pal, bool want);
 	
 	void PaintCT(Surface *surfaceWindow);
 	
-	// Setup the calltip and return a rectangle of the area required
+	/// Setup the calltip and return a rectangle of the area required.
 	PRectangle CallTipStart(int pos, Point pt, const char *defn, 
 		const char *faceName, int size);
 		
 	void CallTipCancel();
 	
-	// Set a range of characters to be displayed in a highlight style.
-	// Commonly used to highlight the current parameter.
+	/// Set a range of characters to be displayed in a highlight style.
+	/// Commonly used to highlight the current parameter.
 	void SetHighlight(int start, int end);
 };
 
diff --git a/src/CellBuffer.cxx b/src/CellBuffer.cxx
index 690e84c94..84ff1d94d 100644
--- a/src/CellBuffer.cxx
+++ b/src/CellBuffer.cxx
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// CellBuffer.cxx - manages a buffer of cells
+/** @file CellBuffer.cxx
+ ** Manages a buffer of cells.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/CellBuffer.h b/src/CellBuffer.h
index 7cd79336d..d078c22c0 100644
--- a/src/CellBuffer.h
+++ b/src/CellBuffer.h
@@ -1,28 +1,35 @@
 // Scintilla source code edit control
-// CellBuffer.h - manages the text of the document
+/** @file CellBuffer.h
+ ** Manages the text of the document.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
 #ifndef CELLBUFFER_H
 #define CELLBUFFER_H
 
-// This holds the marker identifier and the marker type to display.
-// MarkerHandleNumbers are members of lists.
+/**
+ * This holds the marker identifier and the marker type to display.
+ * MarkerHandleNumbers are members of lists.
+ */
 struct MarkerHandleNumber {
 	int handle;
 	int number;
 	MarkerHandleNumber *next;
 };
 
-// A marker handle set contains any number of MarkerHandleNumbers
+/**
+ * A marker handle set contains any number of MarkerHandleNumbers.
+ */
 class MarkerHandleSet {
 	MarkerHandleNumber *root;
+
 public:
 	MarkerHandleSet();
 	~MarkerHandleSet();
 	int Length();
 	int NumberFromHandle(int handle);
-	int MarkValue();	// Bit set of marker numbers
+	int MarkValue();	///< Bit set of marker numbers.
 	bool Contains(int handle);
 	bool InsertHandle(int handle, int markerNum);
 	void RemoveHandle(int handle);
@@ -30,8 +37,10 @@ public:
 	void CombineWith(MarkerHandleSet *other);
 };
 
-// Each line stores the starting position of the first character of the line in the cell buffer
-// and potentially a marker handle set. Often a line will not have any attached markers.
+/**
+ * Each line stores the starting position of the first character of the line in the cell buffer
+ * and potentially a marker handle set. Often a line will not have any attached markers.
+ */
 struct LineData {
 	int startPosition;
 	MarkerHandleSet *handleSet;
@@ -39,7 +48,9 @@ struct LineData {
 	}
 };
 
-// The line vector contains information about each of the lines in a cell buffer.
+/**
+ * The line vector contains information about each of the lines in a cell buffer.
+ */
 class LineVector {
 public:
 	enum { growSize = 4000 };
@@ -49,7 +60,7 @@ public:
 	int *levels;
 	int sizeLevels;
 	
-	// Handles are allocated sequentially and should never have to be reused as 32 bit ints are very big.
+	/// Handles are allocated sequentially and should never have to be reused as 32 bit ints are very big.
 	int handleCurrent;
 	
 	LineVector();
@@ -71,9 +82,11 @@ public:
 	int LineFromHandle(int markerHandle);
 };
 
-// Actions are used to store all the information required to perform one undo/redo step.
 enum actionType { insertAction, removeAction, startAction };
 
+/**
+ * Actions are used to store all the information required to perform one undo/redo step.
+ */
 class Action {
 public:
 	actionType at;
@@ -89,6 +102,9 @@ public:
 	void Grab(Action *source);
 };
 
+/**
+ *
+ */
 class UndoHistory {
 	Action *actions;
 	int lenActions;
@@ -110,13 +126,13 @@ public:
 	void DropUndoSequence();
 	void DeleteUndoHistory();
 	
-	// The save point is a marker in the undo stack where the container has stated that 
-	// the buffer was saved. Undo and redo can move over the save point.
+	/// The save point is a marker in the undo stack where the container has stated that
+	/// the buffer was saved. Undo and redo can move over the save point.
 	void SetSavePoint();
 	bool IsSavePoint() const;
 
-	// To perform an undo, StartUndo is called to retrieve the number of steps, then UndoStep is 
-	// called that many times. Similarly for redo.
+	/// To perform an undo, StartUndo is called to retrieve the number of steps, then UndoStep is
+	/// called that many times. Similarly for redo.
 	bool CanUndo() const;
 	int StartUndo();
 	const Action &GetUndoStep() const;
@@ -127,9 +143,11 @@ public:
 	void CompletedRedoStep();
 };
 
-// Holder for an expandable array of characters that supports undo and line markers
-// Based on article "Data Structures in a Bit-Mapped Text Editor"
-// by Wilfred J. Hansen, Byte January 1987, page 183
+/**
+ * Holder for an expandable array of characters that supports undo and line markers.
+ * Based on article "Data Structures in a Bit-Mapped Text Editor"
+ * by Wilfred J. Hansen, Byte January 1987, page 183.
+ */
 class CellBuffer {
 private:
 	char *body;
@@ -158,7 +176,7 @@ public:
 	CellBuffer(int initialLength = 4000);
 	~CellBuffer();
 	
-	// Retrieving positions outside the range of the buffer works and returns 0
+	/// Retrieving positions outside the range of the buffer works and returns 0
 	char CharAt(int position);
 	void GetCharRange(char *buffer, int position, int lengthRetrieve);
 	char StyleAt(int position);
@@ -171,8 +189,8 @@ public:
 	const char *InsertString(int position, char *s, int insertLength);
 	void InsertCharStyle(int position, char ch, char style);
 	
-	// Setting styles for positions outside the range of the buffer is safe and has no effect.
-	// True is returned if the style of a character changed.
+	/// Setting styles for positions outside the range of the buffer is safe and has no effect.
+	/// @return true if the style of a character is changed.
 	bool SetStyleAt(int position, char style, char mask='\377');
 	bool SetStyleFor(int position, int length, char style, char mask);
 	
@@ -181,12 +199,12 @@ public:
 	bool IsReadOnly();
 	void SetReadOnly(bool set);
 
-	// The save point is a marker in the undo stack where the container has stated that 
-	// the buffer was saved. Undo and redo can move over the save point.
+	/// The save point is a marker in the undo stack where the container has stated that
+	/// the buffer was saved. Undo and redo can move over the save point.
 	void SetSavePoint();
 	bool IsSavePoint();
 
-	// Line marker functions
+	/// Line marker functions
 	int AddMark(int line, int markerNum);
 	void DeleteMark(int line, int markerNum);
 	void DeleteMarkFromHandle(int markerHandle);
@@ -194,7 +212,7 @@ public:
 	void DeleteAllMarks(int markerNum);
 	int LineFromHandle(int markerHandle);
  
-	// Without undo
+	/// Actions without undo
 	void BasicInsertString(int position, char *s, int insertLength);
 	void BasicDeleteChars(int position, int deleteLength);
 
@@ -204,8 +222,8 @@ public:
 	void EndUndoAction();
 	void DeleteUndoHistory();
 	
-	// To perform an undo, StartUndo is called to retrieve the number of steps, then UndoStep is 
-	// called that many times. Similarly for redo.
+	/// To perform an undo, StartUndo is called to retrieve the number of steps, then UndoStep is
+	/// called that many times. Similarly for redo.
 	bool CanUndo();
 	int StartUndo();
 	const Action &GetUndoStep() const;
diff --git a/src/ContractionState.cxx b/src/ContractionState.cxx
index 742574453..1f1469665 100644
--- a/src/ContractionState.cxx
+++ b/src/ContractionState.cxx
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// ContractionState.cxx - manages visibility of lines for folding
+/** @file ContractionState.cxx
+ ** Manages visibility of lines for folding.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/ContractionState.h b/src/ContractionState.h
index 8e38df12c..0d7881c7b 100644
--- a/src/ContractionState.h
+++ b/src/ContractionState.h
@@ -1,15 +1,19 @@
 // Scintilla source code edit control
-// ContractionState.h - manages visibility of lines for folding
+/** @file ContractionState.h
+ ** Manages visibility of lines for folding.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
 #ifndef CONTRACTIONSTATE_H
 #define CONTRACTIONSTATE_H
 
+/**
+ */
 class OneLine {
 public:
-	int displayLine;	// position within set of visible lines
-	int docLine;		// inverse of displayLine
+	int displayLine;	///< Position within set of visible lines
+	int docLine;		///< Inverse of @a displayLine
 	bool visible;
 	bool expanded;
 	
@@ -17,6 +21,8 @@ public:
 	virtual ~OneLine() {}
 };
 
+/**
+ */
 class ContractionState {
 	void Grow(int sizeNew);
 	enum { growSize = 4000 };
@@ -26,6 +32,7 @@ class ContractionState {
 	int size;
 	mutable bool valid;
 	void MakeValid() const;
+
 public:
 	ContractionState();
 	virtual ~ContractionState();
diff --git a/src/Document.cxx b/src/Document.cxx
index 3ab6b7307..bc9dec5f4 100644
--- a/src/Document.cxx
+++ b/src/Document.cxx
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// Document.cxx - text document that handles notifications, DBCS, styling, words and end of line
+/** @file Document.cxx
+ ** Text document that handles notifications, DBCS, styling, words and end of line.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/Document.h b/src/Document.h
index edd89b44c..4b0b9b1db 100644
--- a/src/Document.h
+++ b/src/Document.h
@@ -1,20 +1,26 @@
 // Scintilla source code edit control
-// Document.h - text document that handles notifications, DBCS, styling, words and end of line
+/** @file Document.h
+ ** Text document that handles notifications, DBCS, styling, words and end of line.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
 #ifndef DOCUMENT_H
 #define DOCUMENT_H
 
-// A Position is a position within a document between two characters or at the beginning or end.
-// Sometimes used as a character index where it identifies the character after the position.
+/**
+ * A Position is a position within a document between two characters or at the beginning or end.
+ * Sometimes used as a character index where it identifies the character after the position.
+ */
 typedef int Position;
 const Position invalidPosition = -1;
 
-// The range class represents a range of text in a document.
-// The two values are not sorted as one end may be more significant than the other
-// as is the case for the selection where the end position is the position of the caret.
-// If either position is invalidPosition then the range is invalid and most operations will fail.
+/**
+ * The range class represents a range of text in a document.
+ * The two values are not sorted as one end may be more significant than the other
+ * as is the case for the selection where the end position is the position of the caret.
+ * If either position is invalidPosition then the range is invalid and most operations will fail.
+ */
 class Range {
 public:
 	Position start;
@@ -55,10 +61,12 @@ public:
 class DocWatcher;
 class DocModification;
 
+/**
+ */
 class Document {
 
 public:
-	// Used to pair watcher pointer with user data
+	/** Used to pair watcher pointer with user data. */
 	class WatcherWithUserData {
 	public:
 		DocWatcher *watcher;
@@ -87,7 +95,7 @@ public:
 	int stylingBitsMask;
 	
 	int eolMode;
-	// dbcsCodePage can also be SC_CP_UTF8 to enable UTF-8 mode
+	/// Can also be SC_CP_UTF8 to enable UTF-8 mode
 	int dbcsCodePage;
 	int tabInChars;
 	int indentInChars;
@@ -207,16 +215,18 @@ private:
 	int IndentSize() { return indentInChars ? indentInChars : tabInChars; }
 };
 
-// To optimise processing of document modifications by DocWatchers, a hint is passed indicating the 
-// scope of the change.
-// If the DocWatcher is a document view then this can be used to optimise screen updating.
+/**
+ * To optimise processing of document modifications by DocWatchers, a hint is passed indicating the
+ * scope of the change.
+ * If the DocWatcher is a document view then this can be used to optimise screen updating.
+ */
 class DocModification {
 public:
   	int modificationType;
 	int position;
  	int length;
- 	int linesAdded;	// Negative if lines deleted
- 	const char *text;	// Only valid for changes to text, not for changes to style
+ 	int linesAdded;	/**< Negative if lines deleted. */
+ 	const char *text;	/**< Only valid for changes to text, not for changes to style. */
  	int line;
 	int foldLevelNow;
 	int foldLevelPrev;
@@ -243,8 +253,10 @@ public:
 		foldLevelPrev(0) {}
 };
 
-// A class that wants to receive notifications from a Document must be derived from DocWatcher 
-// and implement the notification methods. It can then be added to the watcher list with AddWatcher.
+/**
+ * A class that wants to receive notifications from a Document must be derived from DocWatcher
+ * and implement the notification methods. It can then be added to the watcher list with AddWatcher.
+ */
 class DocWatcher {
 public:
 	virtual ~DocWatcher() {}
diff --git a/src/DocumentAccessor.cxx b/src/DocumentAccessor.cxx
index c4779e1bd..9cce5d5b4 100644
--- a/src/DocumentAccessor.cxx
+++ b/src/DocumentAccessor.cxx
@@ -1,5 +1,7 @@
 // SciTE - Scintilla based Text Editor
-// Accessor.cxx - rapid easy access to contents of a Scintilla
+/** @file DocumentAccessor.cxx
+ ** Rapid easy access to contents of a Scintilla.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/DocumentAccessor.h b/src/DocumentAccessor.h
index ab0be9aba..abbb55f18 100644
--- a/src/DocumentAccessor.h
+++ b/src/DocumentAccessor.h
@@ -1,13 +1,20 @@
-// DocumentAccessor.h - implementation of BufferAccess and StylingAccess on a Scintilla rapid easy access to contents of a Scintilla
+// Scintilla source code edit control
+/** @file DocumentAccessor.h
+ ** Implementation of BufferAccess and StylingAccess on a Scintilla
+ ** rapid easy access to contents of a Scintilla.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
 class Document;
 
+/**
+ */
 class DocumentAccessor : public Accessor {
 	// Private so DocumentAccessor objects can not be copied
 	DocumentAccessor(const DocumentAccessor &source) : Accessor(), props(source.props) {}
 	DocumentAccessor &operator=(const DocumentAccessor &) { return *this; }
+
 protected:
 	Document *pdoc;
 	PropSet &props;
@@ -21,6 +28,7 @@ protected:
 
 	bool InternalIsLeadByte(char ch);
 	void Fill(int position);
+
 public:
 	DocumentAccessor(Document *pdoc_, PropSet &props_) : 
 		Accessor(), pdoc(pdoc_), props(props_), 
diff --git a/src/Editor.cxx b/src/Editor.cxx
index 2b759c96c..0096da7a2 100644
--- a/src/Editor.cxx
+++ b/src/Editor.cxx
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// Editor.cxx - main code for the edit control
+/** @file Editor.cxx
+ ** Main code for the edit control.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
@@ -778,6 +780,11 @@ void DrawTabArrow(Surface *surface, PRectangle rcTab, int ymid) {
 	surface->LineTo(xhead, ymid + ydiff);
 }
 
+/**
+ * Fill in the LineLayout data for the given line.
+ * Copy the given @a line and its styles from the document into local arrays.
+ * Also determine the x position at which each character starts.
+ */
 void Editor::LayoutLine(int line, Surface *surface, ViewStyle &vstyle, LineLayout &ll) {
 	int numCharsInLine = 0;
 	int posLineStart = pdoc->LineStart(line);
@@ -786,9 +793,11 @@ void Editor::LayoutLine(int line, Surface *surface, ViewStyle &vstyle, LineLayou
 	char styleByte = 0;
 	int styleMask = pdoc->stylingBitsMask;
 	ll.xHighlightGuide = 0;
+	// If the line is very long, limit the treatment to a length that should fit in the viewport
 	if (posLineEnd > (posLineStart + LineLayout::maxLineLength)) {
 		posLineEnd = posLineStart + LineLayout::maxLineLength;
 	}
+	// Fill base line layout
 	for (int charInDoc = posLineStart; charInDoc < posLineEnd; charInDoc++) {
 		char chDoc = pdoc->CharAt(charInDoc);
 		styleByte = pdoc->StyleAt(charInDoc);
@@ -806,8 +815,8 @@ void Editor::LayoutLine(int line, Surface *surface, ViewStyle &vstyle, LineLayou
 
 	// Layout the line, determining the position of each character,
 	// with an extra element at the end for the end of the line.
-	int startseg = 0;
-	int startsegx = 0;
+	int startseg = 0;	// Start of the current segment, in char. number
+	int startsegx = 0;	// Start of the current segment, in pixels
 	ll.positions[0] = 0;
 	unsigned int tabWidth = vstyle.spaceWidth * pdoc->tabInChars;
 	bool lastSegItalics = false;
@@ -827,7 +836,7 @@ void Editor::LayoutLine(int line, Surface *surface, ViewStyle &vstyle, LineLayou
 						ll.positions[charInLine + 1] = surface->WidthText(ctrlCharsFont, ctrlChar, strlen(ctrlChar)) + 3;
 					}
 					lastSegItalics = false;
-				} else {
+				} else {	// Regular character
 					lastSegItalics = vstyle.styles[ll.styles[charInLine]].italic;
 					int lenSeg = charInLine - startseg + 1;
 					if ((lenSeg == 1) && (' ' == ll.chars[startseg])) {
@@ -835,7 +844,7 @@ void Editor::LayoutLine(int line, Surface *surface, ViewStyle &vstyle, LineLayou
 						ll.positions[charInLine + 1] = vstyle.styles[ll.styles[charInLine]].spaceWidth;
 					} else {
 						surface->MeasureWidths(vstyle.styles[ll.styles[charInLine]].font, ll.chars + startseg,
-						                       charInLine - startseg + 1, ll.positions + startseg + 1);
+						                       lenSeg, ll.positions + startseg + 1);
 					}
 				}
 			} else {    // invisible
@@ -1140,7 +1149,7 @@ void Editor::Paint(Surface *surfaceWindow, PRectangle rcArea) {
 
 	int screenLinePaintFirst = rcArea.top / vs.lineHeight;
 	// The area to be painted plus one extra line is styled.
-	// The extra line is to determine when a style change, such as statrting a comment flows on to other lines.
+	// The extra line is to determine when a style change, such as starting a comment flows on to other lines.
 	int lineStyleLast = topLine + (rcArea.bottom - 1) / vs.lineHeight + 1;
 	//Platform::DebugPrintf("Paint lines = %d .. %d\n", topLine + screenLinePaintFirst, lineStyleLast);
 	int endPosPaint = pdoc->Length();
@@ -1177,6 +1186,7 @@ void Editor::Paint(Surface *surfaceWindow, PRectangle rcArea) {
 	}
 	//Platform::DebugPrintf("start display %d, offset = %d\n", pdoc->Length(), xOffset);
 
+	// Do the painting
 	if (rcArea.right > vs.fixedColumnWidth) {
 
 		Surface *surface = surfaceWindow;
@@ -1199,11 +1209,27 @@ void Editor::Paint(Surface *surfaceWindow, PRectangle rcArea) {
 		rcTextArea.left = vs.fixedColumnWidth;
 		rcTextArea.right -= vs.rightMarginWidth;
 		surfaceWindow->SetClip(rcTextArea);
+
+		// Loop on visible lines
 		//GTimer *tim=g_timer_new();
 		while (visibleLine < cs.LinesDisplayed() && yposScreen < rcArea.bottom) {
 			//g_timer_start(tim);
 			//Platform::DebugPrintf("Painting line %d\n", line);
 
+			// Copy this line and its styles from the document into local arrays
+			// and determine the x position at which each character starts.
+			LineLayout ll;
+			LayoutLine(line, surface, vs, ll);
+
+			ll.selStart = SelectionStart(line);
+			ll.selEnd = SelectionEnd(line);
+			if (hideSelection) {
+				ll.selStart = -1;
+				ll.selEnd = -1;
+			}
+			// Need to fix this up so takes account of Unicode and DBCS
+			ll.edgeColumn = theEdge;
+
 			int posLineStart = pdoc->LineStart(line);
 			int posLineEnd = pdoc->LineStart(line + 1);
 			//Platform::DebugPrintf("line %d %d - %d\n", line, posLineStart, posLineEnd);
@@ -1212,11 +1238,6 @@ void Editor::Paint(Surface *surfaceWindow, PRectangle rcArea) {
 			rcLine.top = ypos;
 			rcLine.bottom = ypos + vs.lineHeight;
 
-			// Copy this line and its styles from the document into local arrays
-			// and determine the x position at which each character starts.
-			LineLayout ll;
-			LayoutLine(line, surface, vs, ll);
-
 			// Highlight the current braces if any
 			if ((braces[0] >= posLineStart) && (braces[0] < posLineEnd)) {
 				int braceOffset = braces[0] - posLineStart;
@@ -1233,15 +1254,6 @@ void Editor::Paint(Surface *surfaceWindow, PRectangle rcArea) {
 				ll.xHighlightGuide = highlightGuideColumn * vs.spaceWidth;
 			}
 
-			ll.selStart = SelectionStart(line);
-			ll.selEnd = SelectionEnd(line);
-			if (hideSelection) {
-				ll.selStart = -1;
-				ll.selEnd = -1;
-			}
-			// Need to fix this up so takes account of Unicode and DBCS
-			ll.edgeColumn = theEdge;
-
 			// Draw the line
 			if (cs.GetVisible(line))
 				DrawLine(surface, vs, line, visibleLine, xStart, rcLine, ll);
@@ -1320,6 +1332,7 @@ void Editor::Paint(Surface *surfaceWindow, PRectangle rcArea) {
 		}
 		//g_timer_destroy(tim);
 
+		// Right column limit indicator
 		PRectangle rcBeyondEOF = rcClient;
 		rcBeyondEOF.left = vs.fixedColumnWidth;
 		rcBeyondEOF.right = rcBeyondEOF.right;
@@ -1444,6 +1457,21 @@ long Editor::FormatRange(bool draw, RangeToFormat *pfr) {
 
 		while (line <= linePrintLast && ypos < pfr->rc.bottom) {
 
+			// When printing, the hdc and hdcTarget may be the same, so
+			// changing the state of surfaceMeasure may change the underlying
+			// state of surface. Therefore, any cached state is discarded before
+			// using each surface.
+			surfaceMeasure->FlushCachedState();
+
+			// Copy this line and its styles from the document into local arrays
+			// and determine the x position at which each character starts.
+			LineLayout ll;
+			LayoutLine(line, surfaceMeasure, vsPrint, ll);
+			ll.selStart = -1;
+			ll.selEnd = -1;
+			// Need to fix this up so takes account of Unicode and DBCS
+			ll.edgeColumn = theEdge;
+
 			PRectangle rcLine;
 			rcLine.left = pfr->rc.left + lineNumberWidth;
 			rcLine.top = ypos;
@@ -1464,21 +1492,6 @@ long Editor::FormatRange(bool draw, RangeToFormat *pfr) {
 				                  vsPrint.styles[STYLE_LINENUMBER].back.allocated);
 			}
 
-			// When printing, the hdc and hdcTarget may be the same, so
-			// changing the state of surfaceMeasure may change the underlying
-			// state of surface. Therefore, any cached state is discarded before
-			// using each surface.
-
-			// Copy this line and its styles from the document into local arrays
-			// and determine the x position at which each character starts.
-			surfaceMeasure->FlushCachedState();
-			LineLayout ll;
-			LayoutLine(line, surfaceMeasure, vsPrint, ll);
-			ll.selStart = -1;
-			ll.selEnd = -1;
-			// Need to fix this up so takes account of Unicode and DBCS
-			ll.edgeColumn = theEdge;
-
 			// Draw the line
 			surface->FlushCachedState();
 			DrawLine(surface, vsPrint, line, line, xStart, rcLine, ll);
@@ -3269,7 +3282,7 @@ sptr_t Editor::WndProc(unsigned int iMessage, uptr_t wParam, sptr_t lParam) {
 		SetLastXChosen();
 		break;
 
-		// Edit control mesages
+		// Edit control messages
 
 		// Not supported (no-ops):
 		//		EM_GETWORDBREAKPROC
diff --git a/src/Editor.h b/src/Editor.h
index 81806ba77..115c21782 100644
--- a/src/Editor.h
+++ b/src/Editor.h
@@ -1,11 +1,15 @@
 // Scintilla source code edit control
-// Editor.h - defines the main editor class
+/** @file Editor.h
+ ** Defines the main editor class.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
 #ifndef EDITOR_H
 #define EDITOR_H
 
+/**
+ */
 class Caret {
 public:
 	bool active;
@@ -15,8 +19,9 @@ public:
 	Caret();
 };
 
+/**
+ */
 class Timer {
-
 public:
 	bool ticking;
 	int ticksToWait;
@@ -26,9 +31,11 @@ public:
 	Timer();
 };
 
+/**
+ */
 class LineLayout {
 public:
-	// Drawing is only performed for maxLineLength characters on each line.
+	/// Drawing is only performed for @a maxLineLength characters on each line.
 	enum {maxLineLength = 4000};
 	int numCharsInLine;
 	int xHighlightGuide;
@@ -42,18 +49,21 @@ public:
 	int positions[maxLineLength+1];
 };
 
+/**
+ */
 class Editor : public DocWatcher {
 	// Private so Editor objects can not be copied
 	Editor(const Editor &) : DocWatcher() {}
 	Editor &operator=(const Editor &) { return *this; }
+
 protected:	// ScintillaBase subclass needs access to much of Editor
 
-	// On GTK+, Scintilla is a container widget holding two scroll bars
-	// whereas on Windows there is just one window with both scroll bars turned on.
-	Window wMain;	// The Scintilla parent window
+	/** On GTK+, Scintilla is a container widget holding two scroll bars
+	 * whereas on Windows there is just one window with both scroll bars turned on. */
+	Window wMain;	///< The Scintilla parent window
 
-	// Style resources may be expensive to allocate so are cached between uses.
-	// When a style attribute is changed, this cache is flushed.
+	/** Style resources may be expensive to allocate so are cached between uses.
+	 * When a style attribute is changed, this cache is flushed. */
 	bool stylesValid;	
 	ViewStyle vs;
 	Palette palette;
@@ -67,12 +77,12 @@ protected:	// ScintillaBase subclass needs access to much of Editor
 	int errorStatus;
 	bool mouseDownCaptures;
 	
-	// In bufferedDraw mode, graphics operations are drawn to a pixmap and then copied to 
-	// the screen. This avoids flashing but is about 30% slower.
+	/** In bufferedDraw mode, graphics operations are drawn to a pixmap and then copied to
+	 * the screen. This avoids flashing but is about 30% slower. */
 	bool bufferedDraw;
 
-	int xOffset;				// Horizontal scrolled amount in pixels
-	int xCaretMargin;	// Ensure this many pixels visible on both sides of caret
+	int xOffset;		///< Horizontal scrolled amount in pixels
+	int xCaretMargin;	///< Ensure this many pixels visible on both sides of caret
 	bool horizontalScrollBarVisible;
 	
 	Surface pixmapLine;
@@ -82,7 +92,7 @@ protected:	// ScintillaBase subclass needs access to much of Editor
 	Surface pixmapIndentGuideHighlight;
 	// Intellimouse support - currently only implemented for Windows
 	unsigned int ucWheelScrollLines;
-	int cWheelDelta; //wheel delta from roll
+	int cWheelDelta; ///< Wheel delta from roll
 
 	KeyMap kmap;
 
@@ -282,8 +292,8 @@ protected:	// ScintillaBase subclass needs access to much of Editor
 	void DisplayCursor(Window::Cursor c);
 	virtual void StartDrag();
 	void DropAt(int position, const char *value, bool moving, bool rectangular);
-	// PositionInSelection returns 0 if position in selection, -1 if position before selection, and 1 if after.
-	// Before means either before any line of selection or before selection on its line, with a similar meaning to after
+	/** PositionInSelection returns 0 if position in selection, -1 if position before selection, and 1 if after.
+	 * Before means either before any line of selection or before selection on its line, with a similar meaning to after. */
 	int PositionInSelection(int pos);
 	bool PointInSelection(Point pt);
 	bool PointInSelMargin(Point pt);
diff --git a/src/Indicator.cxx b/src/Indicator.cxx
index 9bbe460dc..580e9f86d 100644
--- a/src/Indicator.cxx
+++ b/src/Indicator.cxx
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// Indicator.cxx - defines the style of indicators which are text decorations such as underlining
+/** @file Indicator.cxx
+ ** Defines the style of indicators which are text decorations such as underlining.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/Indicator.h b/src/Indicator.h
index 40e1304da..a19b46b5e 100644
--- a/src/Indicator.h
+++ b/src/Indicator.h
@@ -1,11 +1,15 @@
 // Scintilla source code edit control
-// Indicator.h - defines the style of indicators which are text decorations such as underlining
+/** @file Indicator.h
+ ** Defines the style of indicators which are text decorations such as underlining.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
 #ifndef INDICATOR_H
 #define INDICATOR_H
 
+/**
+ */
 class Indicator {
 public:
 	int style;
diff --git a/src/KeyMap.cxx b/src/KeyMap.cxx
index 724fde455..4ebabc78c 100644
--- a/src/KeyMap.cxx
+++ b/src/KeyMap.cxx
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// KeyMap.cxx  - defines a mapping between keystrokes and commands
+/** @file KeyMap.cxx 
+ ** Defines a mapping between keystrokes and commands.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/KeyMap.h b/src/KeyMap.h
index ad50f1a0e..8232b7160 100644
--- a/src/KeyMap.h
+++ b/src/KeyMap.h
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// KeyMap.h - defines a mapping between keystrokes and commands
+/** @file KeyMap.h
+ ** Defines a mapping between keystrokes and commands.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
@@ -13,6 +15,8 @@
 #define SCI_CSHIFT (SCI_CTRL | SCI_SHIFT)
 #define SCI_ASHIFT (SCI_ALT | SCI_SHIFT)
 
+/**
+ */
 class KeyToCommand {
 public:
 	int key;
@@ -20,11 +24,14 @@ public:
 	unsigned int msg;
 };
 
+/**
+ */
 class KeyMap {
 	KeyToCommand *kmap;
 	int len;
 	int alloc;
 	static KeyToCommand MapDefault[];
+
 public:
 	KeyMap();
 	~KeyMap();
diff --git a/src/KeyWords.cxx b/src/KeyWords.cxx
index 74e3bb928..17c0277de 100644
--- a/src/KeyWords.cxx
+++ b/src/KeyWords.cxx
@@ -1,5 +1,7 @@
 // SciTE - Scintilla based Text Editor
-// KeyWords.cxx - colourise for particular languages
+/** @file KeyWords.cxx
+ ** Colourise for particular languages.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/LexAVE.cxx b/src/LexAVE.cxx
index 6382f6cf7..8ef79c6a3 100644
--- a/src/LexAVE.cxx
+++ b/src/LexAVE.cxx
@@ -1,5 +1,7 @@
 // SciTE - Scintilla based Text Editor
-// LexAVE.cxx - lexer for Avenue
+/** @file LexAVE.cxx
+ ** Lexer for Avenue.
+ **/
 // Copyright 1998-2000 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/LexCPP.cxx b/src/LexCPP.cxx
index bb7644ada..65fd5ff4b 100644
--- a/src/LexCPP.cxx
+++ b/src/LexCPP.cxx
@@ -1,5 +1,7 @@
 // SciTE - Scintilla based Text Editor
-// LexCPP.cxx - lexer for C++, C, Java, and Javascript
+/** @file LexCPP.cxx
+ ** Lexer for C++, C, Java, and Javascript.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/LexHTML.cxx b/src/LexHTML.cxx
index 1c68f576b..800e46fee 100644
--- a/src/LexHTML.cxx
+++ b/src/LexHTML.cxx
@@ -1,5 +1,7 @@
 // SciTE - Scintilla based Text Editor
-// LexHTML.cxx - lexer for HTML
+/** @file LexHTML.cxx
+ ** Lexer for HTML.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/LexPerl.cxx b/src/LexPerl.cxx
index c143c096a..2dc539c0f 100644
--- a/src/LexPerl.cxx
+++ b/src/LexPerl.cxx
@@ -1,5 +1,7 @@
 // SciTE - Scintilla based Text Editor
-// LexPerl.cxx - lexer for subset of Perl
+/** @file LexPerl.cxx
+ ** Lexer for subset of Perl.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/LexPython.cxx b/src/LexPython.cxx
index 1d99e6767..f14dbfe07 100644
--- a/src/LexPython.cxx
+++ b/src/LexPython.cxx
@@ -1,5 +1,7 @@
 // SciTE - Scintilla based Text Editor
-// LexPython.cxx - lexer for Python
+/** @file LexPython.cxx
+ ** Lexer for Python.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/LexSQL.cxx b/src/LexSQL.cxx
index 2747f25c9..eab7d2f71 100644
--- a/src/LexSQL.cxx
+++ b/src/LexSQL.cxx
@@ -1,5 +1,7 @@
 // SciTE - Scintilla based Text Editor
-// LexSQL.cxx - lexer for SQL
+/** @file LexSQL.cxx
+ ** Lexer for SQL.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/LexVB.cxx b/src/LexVB.cxx
index 98c9bf350..3b8c434d6 100644
--- a/src/LexVB.cxx
+++ b/src/LexVB.cxx
@@ -1,5 +1,7 @@
 // SciTE - Scintilla based Text Editor
-// LexVB.cxx - lexer for Visual Basic and VBScript
+/** @file LexVB.cxx
+ ** Lexer for Visual Basic and VBScript.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/LineMarker.cxx b/src/LineMarker.cxx
index 75ef0e3a2..90c2710ce 100644
--- a/src/LineMarker.cxx
+++ b/src/LineMarker.cxx
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// LineMarker.cxx - defines the look of a line marker in the margin 
+/** @file LineMarker.cxx
+ ** Defines the look of a line marker in the margin .
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
diff --git a/src/LineMarker.h b/src/LineMarker.h
index 25d575cb9..ee0f36c25 100644
--- a/src/LineMarker.h
+++ b/src/LineMarker.h
@@ -1,11 +1,15 @@
 // Scintilla source code edit control
-// LineMarker.h - defines the look of a line marker in the margin 
+/** @file LineMarker.h
+ ** Defines the look of a line marker in the margin .
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
 #ifndef LINEMARKER_H
 #define LINEMARKER_H
 
+/**
+ */
 class LineMarker {
 public:
 	int markType;
diff --git a/src/PropSet.cxx b/src/PropSet.cxx
index aa7423cbc..23310c880 100644
--- a/src/PropSet.cxx
+++ b/src/PropSet.cxx
@@ -1,5 +1,7 @@
 // SciTE - Scintilla based Text Editor
-// PropSet.cxx - a java style properties file module
+/** @file PropSet.cxx
+ ** A Java style properties file module.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
 
@@ -443,9 +445,10 @@ bool WordList::InList(const char *s) {
 }
 
 /**
- * Returns an element (complete) of the wordlist array which has the beginning
- * the same as the passed string. The length of the word to compare is passed
- * too. Letter case can be ignored or preserved (default).
+ * Returns an element (complete) of the wordlist array which has
+ * the same beginning as the passed string.
+ * The length of the word to compare is passed too.
+ * Letter case can be ignored or preserved (default).
  */
 const char *WordList::GetNearestWord(const char *wordStart, int searchLen /*= -1*/, bool ignoreCase /*= false*/) {
 	int start = 0; // lower bound of the api array block to search
@@ -489,8 +492,9 @@ const char *WordList::GetNearestWord(const char *wordStart, int searchLen /*= -1
 
 /**
  * Returns elements (first words of them) of the wordlist array which have
- * the beginning the same as the passed string. The length of the word to
- * compare is passed too. Letter case can be ignored or preserved (default).
+ * the same beginning as the passed string.
+ * The length of the word to compare is passed too.
+ * Letter case can be ignored or preserved (default).
  * If there are more words meeting the condition they are returned all of
  * them in the ascending order separated with spaces.
  *