Patch from Philippe, containing comments and a fix to SString for empty

strings.

3 files changed, 70 insertions, 22 deletions

diff --git a/include/Platform.h b/include/Platform.h
index 099e5ee22..d7ccbb9c7 100644
--- a/include/Platform.h
+++ b/include/Platform.h
@@ -4,6 +4,7 @@
 // Implemented in PlatGTK.cxx for GTK+/Linux, PlatWin.cxx for Windows, and PlatWX.cxx for wxWindows
 // Copyright 1998-2000 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
@@ -80,8 +81,9 @@ typedef wxWindow* WindowID;
 typedef wxMenu* MenuID;
 #endif
 
-// Point is exactly the same as the Win32 POINT and GTK+ GdkPoint so can be used interchangeably
-
+/** 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;
@@ -95,8 +97,10 @@ public:
 	static Point FromLong(long lpoint);
 };
 
-// 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
+/** 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;
@@ -131,6 +135,8 @@ wxRect wxRectFromPRectangle(PRectangle prc);
 PRectangle PRectangleFromwxRect(wxRect rc);
 #endif
 
+/** A colour class.
+ **/
 class Colour {
 	ColourID co;
 public:
@@ -146,10 +152,11 @@ public:
 	friend class Palette;
 };
 
-// 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.
+/** 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;
@@ -162,6 +169,8 @@ struct ColourPair {
 
 class Window;	// Forward declaration for Palette
 
+/** Colour palette management.
+ **/
 class Palette {
 	int used;
 	enum {numEntries = 100};
@@ -182,9 +191,10 @@ public:
 
 	void Release();
 	
-	// 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.
+	/** 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);
@@ -192,6 +202,8 @@ public:
 	friend class Surface;
 };
 
+/** Font management.
+ **/
 class Font {
 protected:
 	FontID id;
@@ -214,7 +226,8 @@ public:
 	friend class Surface;
 };
 
-// A surface abstracts a place to draw
+/** A surface abstracts a place to draw.
+ **/
 class Surface {
 private:
 	bool unicodeMode;
@@ -297,8 +310,9 @@ public:
 	}
 };
 
-// Class to hide the details of window manipulation
-// Does not own the window which will normally have a longer life than this object
+/** 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:
@@ -333,6 +347,8 @@ public:
 #endif
 };
 
+/** Listbox management.
+ **/
 class ListBox : public Window {
 #if PLAT_GTK
 	WindowID list;
@@ -360,6 +376,8 @@ public:
 	void Sort();
 };
 
+/** Menu management.
+ **/
 class Menu {
 	MenuID id;
 public:
@@ -370,8 +388,9 @@ public:
 	void Show(Point pt, Window &w);
 };
 
-// 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.
+/** 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/SString.h b/include/SString.h
index 5374f26e5..2fff61645 100644
--- a/include/SString.h
+++ b/include/SString.h
@@ -2,6 +2,7 @@
 // SString.h - a simple string class
 // Copyright 1998-2000 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
@@ -17,7 +18,15 @@ 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.
 
-inline char *StringDup(const char *s, int len=-1) {
+/** 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.
+{
 	if (!s)
 		return 0;
 	if (len == -1)
@@ -30,12 +39,19 @@ inline char *StringDup(const char *s, int len=-1) {
 	return sNew;
 }
 
+/** 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
+ * functions to allow reliable manipulations of these strings.
+ **/
 class SString {
 	char *s;		///< The C string
 	int ssize;		///< The size of the buffer, less 1: ie. the maximum size of the string
 	int slen;		///< The size of the string in s
 
-	enum { sizingGranularity = 64 };	// Minimum growth size when appending strings
+	/// Minimum growth size when appending strings
+	enum { sizingGranularity = 64 };
 
 public:
 	typedef const char* const_iterator;
@@ -59,7 +75,7 @@ public:
 		ssize = slen = (s) ? strlen(s) : 0;
 	}
 	SString(int i) {
-		char number[100];
+		char number[32];
 		sprintf(number, "%0d", i);
 		s = StringDup(number);
 		ssize = slen = (s) ? strlen(s) : 0;
@@ -92,17 +108,27 @@ public:
 		return slen;
 	}
 	SString &assign(const char* sother, int size_ = -1) {
+		if (!sother) {
+			size_ = 0;
+		}
 		if (size_ < 0) {
 			size_ = strlen(sother);
 		}
 		if (ssize > 0 && size_ <= ssize) {	// Does not allocate new buffer if the current is big enough
+			if (s && size_) {
 			strncpy(s, sother, size_);
+			}
 			s[size_] = '\0';
+			slen = size_;
 		} else {
 			delete []s;
 			s = StringDup(sother, size_);
+			if (s) {
 			ssize = size_;	// Allow buffer bigger than real string, thus providing space to grow
-			slen = (s) ? strlen(s) : 0;
+				slen = strlen(s);
+			} else {
+				ssize = slen = 0;
+			}
 		}
 		return *this;
 	}
@@ -112,6 +138,9 @@ public:
 	SString &assign(const_iterator ibeg, const_iterator iend) {
 		return assign(ibeg, iend - ibeg);
 	}
+	SString &operator=(const char *source) {
+		return assign(source);
+	}
 	SString &operator=(const SString &source) {
 		if (this != &source) {
 			assign(source.c_str());
diff --git a/win32/PlatWin.cxx b/win32/PlatWin.cxx
index d2f76c916..eca767f8b 100644
--- a/win32/PlatWin.cxx
+++ b/win32/PlatWin.cxx
@@ -314,9 +314,9 @@ void Surface::Init() {
 	::SetTextAlign(hdc, TA_BASELINE);
 }
 
-void Surface::Init(HDC hdc_) {
+void Surface::Init(SurfaceID sid) {
 	Release();
-	hdc = hdc_;
+	hdc = sid;
 	::SetTextAlign(hdc, TA_BASELINE);
 }