Updated documentation comments from Philippe.

10 files changed, 106 insertions, 56 deletions

diff --git a/include/Accessor.h b/include/Accessor.h
index 3c858093d..5254d2264 100644
--- a/include/Accessor.h
+++ b/include/Accessor.h
@@ -1,5 +1,7 @@
-// SciTE - Scintilla based Text Editor
-// Accessor.h - rapid easy access to contents of a Scintilla
+// Scintilla source code edit control
+/** @file Accessor.h
+ ** 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.
 
@@ -9,12 +11,16 @@ class Accessor;
 
 typedef bool (*PFNIsCommentLeader)(Accessor &styler, int pos, int len);
 
-// Interface to data in a Scintilla
+/**
+ * Interface to data in a Scintilla.
+ */
 class Accessor {
 protected:
 	enum {extremePosition=0x7FFFFFFF};
-	// bufferSize is a trade off between time taken to copy the characters and retrieval overhead
-	// slopSize positions the buffer before the desired position in case there is some backtracking
+	/** @a bufferSize is a trade off between time taken to copy the characters
+	 * and retrieval overhead.
+	 * @a slopSize positions the buffer before the desired position
+	 * in case there is some backtracking. */
 	enum {bufferSize=4000, slopSize=bufferSize/8};
 	char buf[bufferSize+1];
 	int startPos;
@@ -23,6 +29,7 @@ protected:
 
 	virtual bool InternalIsLeadByte(char ch)=0;
 	virtual void Fill(int position)=0;
+
 public:
 	Accessor() : startPos(extremePosition), endPos(0), codePage(0) {}
 	virtual ~Accessor() {}
@@ -32,8 +39,8 @@ public:
 		}
 		return buf[position - startPos];
 	}
+	/** Safe version of operator[], returning a defined value for invalid position. */
 	char SafeGetCharAt(int position, char chDefault=' ') {
-		// Safe version of operator[], returning a defined value for invalid position 
 		if (position < startPos || position >= endPos) {
 			Fill(position);
 			if (position < startPos || position >= endPos) {
@@ -67,4 +74,3 @@ public:
 	virtual void SetLevel(int line, int level)=0;
 	virtual int IndentAmount(int line, int *flags, PFNIsCommentLeader pfnIsCommentLeader = 0)=0;
 };
-
diff --git a/include/KeyWords.h b/include/KeyWords.h
index 8d4d302b1..d589d1228 100644
--- a/include/KeyWords.h
+++ b/include/KeyWords.h
@@ -1,23 +1,31 @@
-// SciTE - Scintilla based Text Editor
-// KeyWords.h - colourise for particular languages
+// Scintilla source code edit control
+/** @file KeyWords.h
+ ** 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.
 
 typedef void (*LexerFunction)(unsigned int startPos, int lengthDoc, int initStyle,
                   WordList *keywordlists[], Accessor &styler);
                   
+/**
+ */
 class LexerModule {
 	static LexerModule *base;
 	LexerModule *next;
 	int language;
 	LexerFunction fn;
+
 public:
 	LexerModule(int language_, LexerFunction fn_);
 	static void Colourise(unsigned int startPos, int lengthDoc, int initStyle,
                   int language, WordList *keywordlists[], Accessor &styler);
 };
 
-// This is ASCII specific but is safe with chars >= 0x80
+/**
+ * Check if a character is a space.
+ * This is ASCII specific but is safe with chars >= 0x80.
+ */
 inline bool isspacechar(unsigned char ch) {
     return (ch == ' ') || ((ch >= 0x09) && (ch <= 0x0d));
 }
@@ -43,4 +51,3 @@ inline bool isoperator(char ch) {
 		return true;
 	return false;
 }
-
diff --git a/include/Platform.h b/include/Platform.h
index 255423bb5..d2221de64 100644
--- a/include/Platform.h
+++ b/include/Platform.h
@@ -1,10 +1,10 @@
 // Scintilla source code edit control
-// Platform.h - interface to platform facilities
-// Also includes some basic utilities
-// Implemented in PlatGTK.cxx for GTK+/Linux, PlatWin.cxx for Windows, and PlatWX.cxx for wxWindows
+/** @file Platform.h
+ ** Interface to platform facilities. Also includes some basic utilities.
+ ** Implemented in PlatGTK.cxx for GTK+/Linux, PlatWin.cxx for Windows, and PlatWX.cxx for wxWindows.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
-/** @file **/
 
 #ifndef PLATFORM_H
 #define PLATFORM_H
@@ -84,9 +84,10 @@ typedef wxWindow* WindowID;
 typedef wxMenu* MenuID;
 #endif
 
-/** A geometric point class.
+/**
+ * A geometric point class.
  * Point is exactly the same as the Win32 POINT and GTK+ GdkPoint so can be used interchangeably.
- **/
+ */
 class Point {
 public:
 	int x;
@@ -100,10 +101,11 @@ public:
 	static Point FromLong(long lpoint);
 };
 
-/** A geometric rectangle class.
+/**
+ * A geometric rectangle class.
  * PRectangle is exactly the same as the Win32 RECT so can be used interchangeably.
  * PRectangles contain their top and left sides, but not their right and bottom sides.
- **/
+ */
 class PRectangle {
 public:
 	int left;
@@ -138,8 +140,9 @@ wxRect wxRectFromPRectangle(PRectangle prc);
 PRectangle PRectangleFromwxRect(wxRect rc);
 #endif
 
-/** A colour class.
- **/
+/**
+ * A colour class.
+ */
 class Colour {
 	ColourID co;
 public:
@@ -155,11 +158,12 @@ public:
 	friend class Palette;
 };
 
-/** Colour pairs hold a desired colour and the colour that the graphics engine
+/**
+ * Colour pairs hold a desired colour and the colour that the graphics engine
  * allocates to approximate the desired colour.
  * To make palette management more automatic, ColourPairs could register at
  * construction time with a palette management object.
- **/
+ */
 struct ColourPair {
 	Colour desired;
 	Colour allocated;
@@ -172,8 +176,9 @@ struct ColourPair {
 
 class Window;	// Forward declaration for Palette
 
-/** Colour palette management.
- **/
+/**
+ * Colour palette management.
+ */
 class Palette {
 	int used;
 	enum {numEntries = 100};
@@ -194,10 +199,11 @@ public:
 
 	void Release();
 	
-	/** This method either adds a colour to the list of wanted colours (want==true)
+	/**
+	 * This method either adds a colour to the list of wanted colours (want==true)
 	 * or retrieves the allocated colour back to the ColourPair.
 	 * This is one method to make it easier to keep the code for wanting and retrieving in sync.
-	 **/
+	 */
 	void WantFind(ColourPair &cp, bool want);
 
 	void Allocate(Window &w);
@@ -205,8 +211,9 @@ public:
 	friend class Surface;
 };
 
-/** Font management.
- **/
+/**
+ * Font management.
+ */
 class Font {
 protected:
 	FontID id;
@@ -229,8 +236,9 @@ public:
 	friend class Surface;
 };
 
-/** A surface abstracts a place to draw.
- **/
+/**
+ * A surface abstracts a place to draw.
+ */
 class Surface {
 private:
 	bool unicodeMode;
@@ -313,9 +321,10 @@ public:
 	}
 };
 
-/** Class to hide the details of window manipulation.
+/**
+ * Class to hide the details of window manipulation.
  * Does not own the window which will normally have a longer life than this object.
- **/
+ */
 class Window {
 	friend class ListBox;
 protected:
@@ -350,8 +359,9 @@ public:
 #endif
 };
 
-/** Listbox management.
- **/
+/**
+ * Listbox management.
+ */
 class ListBox : public Window {
 #if PLAT_GTK
 	WindowID list;
@@ -379,8 +389,9 @@ public:
 	void Sort();
 };
 
-/** Menu management.
- **/
+/**
+ * Menu management.
+ */
 class Menu {
 	MenuID id;
 public:
@@ -391,9 +402,10 @@ public:
 	void Show(Point pt, Window &w);
 };
 
-/** Platform class used to retrieve system wide parameters such as double click speed
+/**
+ * Platform class used to retrieve system wide parameters such as double click speed
  * and chrome colour. Not a creatable object, more of a module with several functions.
- **/
+ */
 class Platform {
 	// Private so Platform objects can not be copied
 	Platform(const Platform &) {}
diff --git a/include/PropSet.h b/include/PropSet.h
index 3b22725da..90e0a266f 100644
--- a/include/PropSet.h
+++ b/include/PropSet.h
@@ -1,5 +1,7 @@
-// SciTE - Scintilla based Text Editor
-// PropSet.h - a java style properties file module
+// Scintilla source code edit control
+/** @file PropSet.h
+ ** 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.
 
@@ -19,6 +21,8 @@ struct Property {
 	Property() : hash(0), key(0), val(0), next(0) {}
 };
 
+/**
+ */
 class PropSet {
 private:
 	enum { hashRoots=31 };
@@ -38,14 +42,16 @@ public:
 	void Clear();
 };
 
+/**
+ */
 class WordList {
 public:
-	// Each word contains at least one character - a empty word acts as sentinal at the end.
+	// Each word contains at least one character - a empty word acts as sentinel at the end.
 	char **words;
 	char **wordsNoCase;
 	char *list;
 	int len;
-	bool onlyLineEnds;	// Delimited by any white space or only line ends
+	bool onlyLineEnds;	///< Delimited by any white space or only line ends
 	bool sorted;
 	int starts[256];
 	WordList(bool onlyLineEnds_ = false) : 
diff --git a/include/SString.h b/include/SString.h
index df9c88c83..9392e8053 100644
--- a/include/SString.h
+++ b/include/SString.h
@@ -1,8 +1,9 @@
 // SciTE - Scintilla based Text Editor
-// SString.h - a simple string class
+/** @file SString.h
+ ** A simple string class.
+ **/
 // Copyright 1998-2001 by Neil Hodgson <neilh@scintilla.org>
 // The License.txt file describes the conditions under which this software may be distributed.
-/** @file **/
 
 #ifndef SSTRING_H
 #define SSTRING_H
@@ -16,11 +17,12 @@ bool EqualCaseInsensitive(const char *a, const char *b);
 // While it would be 'better' to use std::string, that doubles the executable size.
 // An SString may contain embedded nul characters.
 
-/** Duplicate a C string.
+/**
+ * Duplicate a C string.
  * Allocate memory of the given size, or big enough to fit the string if length isn't given;
  * then copy the given string in the allocated memory.
  * @return the pointer to the new string
- **/
+ */
 inline char *StringDup(
 	const char *s,	///< The string to duplicate
 	int len=-1)		///< The length of memory to allocate. Optional.
@@ -37,7 +39,8 @@ inline char *StringDup(
 	return sNew;
 }
 
-/** A simple string class.
+/**
+ * @brief A simple string class.
  * Hold the length of the string for quick operations,
  * can have a buffer bigger than the string to avoid too many memory allocations and copies.
  * May have embedded zeroes as a result of @a substitute, but rely too heavily on C string
@@ -96,13 +99,15 @@ public:
 	const char* end(void) const {
 		return &s[slen];	// Point after the last character
 	}
-	size_type size(void) const {	// Size of buffer
+	/** Size of buffer. */
+	size_type size(void) const {	///<
 		if (s)
 			return ssize;
 		else
 			return 0;
 	}
-	int length() const {	// Size of string in buffer
+	/** Size of string in buffer. */
+	int length() const {
 		return slen;
 	}
 	SString &assign(const char* sother, int size_ = -1) {
diff --git a/include/SciLexer.h b/include/SciLexer.h
index 54c82c535..9960b8531 100644
--- a/include/SciLexer.h
+++ b/include/SciLexer.h
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// SciLexer - interface to the added lexer functions in the SciLexer version of the edit control
+/** @file SciLexer.h
+ ** Interface to the added lexer functions in the SciLexer version of 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.
 
diff --git a/include/Scintilla.h b/include/Scintilla.h
index f78fa7c31..833418171 100644
--- a/include/Scintilla.h
+++ b/include/Scintilla.h
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// Scintilla.h - interface to the edit control
+/** @file Scintilla.h
+ ** Interface to 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.
 
diff --git a/include/ScintillaWidget.h b/include/ScintillaWidget.h
index a151b9cb2..f6c2fc354 100644
--- a/include/ScintillaWidget.h
+++ b/include/ScintillaWidget.h
@@ -1,6 +1,8 @@
 // Scintilla source code edit control
-// ScintillaWidget.h - definition of Scintilla widget for GTK+
-// Only needed by GTK+ code but is harmless on other platforms.
+/** @file ScintillaWidget.h
+ ** Definition of Scintilla widget for GTK+.
+ ** Only needed by GTK+ code but is harmless on other platforms.
+ **/
 // 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/include/WinDefs.h b/include/WinDefs.h
index 3a056ba4c..bab41662e 100644
--- a/include/WinDefs.h
+++ b/include/WinDefs.h
@@ -1,5 +1,7 @@
 // Scintilla source code edit control
-// WinDefs.h - the subset of definitions from Windows needed by Scintilla for GTK+
+/** @file WinDefs.h
+ ** The subset of definitions from Windows needed by Scintilla for GTK+.
+ **/
 // 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/include/WindowAccessor.h b/include/WindowAccessor.h
index b1f53f70e..4810a4aa9 100644
--- a/include/WindowAccessor.h
+++ b/include/WindowAccessor.h
@@ -1,7 +1,13 @@
-// WindowAccessor.h - implementation of BufferAccess and StylingAccess on a Scintilla rapid easy access to contents of a Scintilla
+// Scintilla source code edit control
+/** @file WindowAccessor.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 WindowAccessor : public Accessor {
 	// Private so WindowAccessor objects can not be copied
 	WindowAccessor(const WindowAccessor &source) : Accessor(), props(source.props) {}