Added doxygen comments for all relevant headers in platform.

platform/CMSWindowsClipboard.h

@@ -8,6 +8,7 @@
 
 class IMSWindowsClipboardConverter;
 
+//! Microsoft windows clipboard implementation
 class CMSWindowsClipboard : public IClipboard {
 public:
 	CMSWindowsClipboard(HWND window);
@@ -37,6 +38,11 @@ private:
 	ConverterList		m_converters;
 };
 
+//! Clipboard format converter interface
+/*!
+This interface defines the methods common to all win32 clipboard format
+converters.
+*/
 class IMSWindowsClipboardConverter : public IInterface {
 public:
 	// accessors

platform/CMSWindowsClipboardAnyTextConverter.h

@@ -3,6 +3,7 @@
 
 #include "CMSWindowsClipboard.h"
 
+//! Convert to/from some text encoding
 class CMSWindowsClipboardAnyTextConverter :
 				public IMSWindowsClipboardConverter {
 public:
@@ -17,11 +18,20 @@ public:
 	virtual CString		toIClipboard(HANDLE) const;
 
 protected:
-	// do UTF-8 conversion only.  memory handle allocation and
+	//! Convert from IClipboard format
-	// linefeed conversion is done by this class.  doFromIClipboard()
+	/*!
-	// must include the nul terminator in the returned string (not
+	Do UTF-8 conversion only.  Memory handle allocation and
-	// including the CString's nul terminator).
+	linefeed conversion is done by this class.  doFromIClipboard()
+	must include the nul terminator in the returned string (not
+	including the CString's nul terminator).
+	*/
 	virtual CString		doFromIClipboard(const CString&) const = 0;
+
+	//! Convert to IClipboard format
+	/*!
+	Do UTF-8 conversion only.  Memory handle allocation and
+	linefeed conversion is done by this class.
+	*/
 	virtual CString		doToIClipboard(const CString&) const = 0;
 
 private:

platform/CMSWindowsClipboardTextConverter.h

@@ -3,6 +3,7 @@
 
 #include "CMSWindowsClipboardAnyTextConverter.h"
 
+//! Convert to/from locale text encoding
 class CMSWindowsClipboardTextConverter :
 				public CMSWindowsClipboardAnyTextConverter {
 public:

platform/CMSWindowsClipboardUTF16Converter.h

@@ -3,6 +3,7 @@
 
 #include "CMSWindowsClipboardAnyTextConverter.h"
 
+//! Convert to/from UTF-16 encoding
 class CMSWindowsClipboardUTF16Converter :
 				public CMSWindowsClipboardAnyTextConverter {
 public:

platform/CMSWindowsScreen.h

@@ -11,6 +11,7 @@
 class CMSWindowsScreenSaver;
 class CThread;
 
+// Microsoft windows event
 class CEvent {
 public:
 	MSG					m_msg;
@@ -20,30 +21,53 @@ public:
 class IScreenReceiver;
 class IMSWindowsScreenEventHandler;
 
+// Microsoft windows screen implementation
 class CMSWindowsScreen : public IScreen {
 public:
 	CMSWindowsScreen(IScreenReceiver*, IMSWindowsScreenEventHandler*);
 	virtual ~CMSWindowsScreen();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
+	//! Initialize
+	/*!
+	Saves the application's HINSTANCE.  This \b must be called by
+	WinMain with the HINSTANCE it was passed.
+	*/
 	static void			init(HINSTANCE);
 
-	// open the desktop and create and return the window.  returns NULL
+	//! Open desktop
-	// on failure.
+	/*!
+	Open the desktop and create and return the window.  Returns NULL
+	on failure.
+	*/
 	HWND				openDesktop();
 
-	// close the window and desktop
+	//! Close desktop
+	/*!
+	Close the window and desktop.
+	*/
 	void				closeDesktop();
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// returns true iff the system appears to have multiple monitors
+	//! Test for multiple monitors
+	/*!
+	Returns true iff the system appears to have multiple monitors.
+	*/
 	bool				isMultimon() const;
 
-	// get the application instance handle
+	//! Get instance
+	/*!
+	Returns the application instance handle passed to init().
+	*/
 	static HINSTANCE	getInstance();
 
+	//@}
+
 	// IScreen overrides
 	// note -- this class expects the hook DLL to have been loaded
 	// and initialized before open() is called.

platform/CMSWindowsScreenSaver.h

@@ -7,19 +7,26 @@
 
 class CThread;
 
+//! Microsoft windows screen saver implementation
 class CMSWindowsScreenSaver : public IScreenSaver {
 public:
 	CMSWindowsScreenSaver();
 	virtual ~CMSWindowsScreenSaver();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// check if the screen saver really started.  returns false if it
+	//! Check if screen saver started
-	// hasn't, true otherwise.  when the screen saver stops msg will
+	/*!
-	// be posted to the current thread's message queue with the given
+	Check if the screen saver really started.  Returns false if it
-	// parameters.
+	hasn't, true otherwise.  When the screen saver stops, \c msg will
+	be posted to the current thread's message queue with the given
+	parameters.
+	*/
 	bool				checkStarted(UINT msg, WPARAM, LPARAM);
 
+	//@}
+
 	// IScreenSaver overrides
 	virtual void		enable();
 	virtual void		disable();

platform/CUnixPlatform.h

@@ -3,6 +3,7 @@
 
 #include "IPlatform.h"
 
+//! Unix platform dependent functions
 class CUnixPlatform : public IPlatform {
 public:
 	CUnixPlatform();

platform/CWin32Platform.h

@@ -7,6 +7,7 @@
 #define WIN32_LEAN_AND_MEAN
 #include <windows.h>
 
+//! Microsoft windows platform dependent functions
 class CWin32Platform : public IPlatform {
 public:
 	typedef int			(*RunFunc)(CMutex*);
@@ -15,24 +16,35 @@ public:
 	CWin32Platform();
 	virtual ~CWin32Platform();
 
-	// returns true iff the platform is win95/98/me
+	//! Test if windows 95, et al.
+	/*!
+	Returns true iff the platform is win95/98/me.
+	*/
 	static bool			isWindows95Family();
 
-	// utility for calling SetServiceStatus()
+	//! Utility for calling SetServiceStatus()
 	static void			setStatus(SERVICE_STATUS_HANDLE, DWORD state);
+	//! Utility for calling SetServiceStatus()
 	static void			setStatus(SERVICE_STATUS_HANDLE,
 							DWORD state, DWORD step, DWORD waitHint);
+	//! Utility for calling SetServiceStatus()
 	static void			setStatusError(SERVICE_STATUS_HANDLE, DWORD error);
 
-	// run a service.  the RunFunc should unlock the passed in mutex
+	//! Run service
-	// (which will be locked on entry) when not initializing or
+	/*!
-	// shutting down (i.e. when running its loop).  StopFunc should
+	Run a service.  The RunFunc should unlock the passed in mutex
-	// cause the RunFunc() to return.  returns what RunFunc returns.
+	(which will be locked on entry) when not initializing or
-	// RunFunc should throw CDaemonFailed if the service fails.
+	shutting down (i.e. when running its loop).  StopFunc should
+	cause the RunFunc() to return.  Returns what RunFunc returns.
+	RunFunc should throw CDaemonFailed if the service fails.
+	*/
 	int					runDaemon(RunFunc, StopFunc);
 
-	// thrown by RunFunc on service failure.  result is the error
+	//! Daemon failed exception
-	// code reported by the service.
+	/*!
+	Thrown by RunFunc on service failure.  Result is the error
+	code reported by the service.
+	*/
 	class CDaemonFailed {
 	public:
 		CDaemonFailed(int result) : m_result(result) { }

platform/CXWindowsClipboard.h

@@ -14,34 +14,58 @@
 
 class IXWindowsClipboardConverter;
 
+//! X11 clipboard implementation
 class CXWindowsClipboard : public IClipboard {
 public:
-	CXWindowsClipboard(Display*, Window, ClipboardID);
+	/*!
+	Use \c window as the window that owns or interacts with the
+	clipboard identified by \c id.
+	*/
+	CXWindowsClipboard(Display*, Window window, ClipboardID id);
 	virtual ~CXWindowsClipboard();
 
-	// tell clipboard it lost ownership
+	//! Notify clipboard was lost
+	/*!
+	Tells clipboard it lost ownership at the given time.
+	*/
 	void				lost(Time);
 
-	// add a selection request to the request list.  if the given
+	//! Add clipboard request
-	// owner window isn't this clipboard's window then this simply
+	/*!
-	// sends a failure event to the requestor.
+	Adds a selection request to the request list.  If the given
+	owner window isn't this clipboard's window then this simply
+	sends a failure event to the requestor.
+	*/
 	void				addRequest(Window owner,
 							Window requestor, Atom target,
 							::Time time, Atom property);
 
-	// continue processing a selection request.  returns true if the
+	//! Process clipboard request
-	// request was handled, false if the request was unknown.
+	/*!
+	Continues processing a selection request.  Returns true if the
+	request was handled, false if the request was unknown.
+	*/
 	bool				processRequest(Window requestor,
 							::Time time, Atom property);
 
-	// terminate a selection request.  returns true iff the request
+	//! Cancel clipboard request
-	// was known and handled.
+	/*!
+	Terminate a selection request.  Returns true iff the request
+	was known and handled.
+	*/
 	bool				destroyRequest(Window requestor);
 
-	// get the clipboard's window
+	//! Get window
+	/*!
+	Returns the clipboard's window (passed the c'tor).
+	*/
 	Window				getWindow() const;
 
-	// get the clipboard selection atom
+	//! Get selection atom
+	/*!
+	Returns the selection atom that identifies the clipboard to X11
+	(e.g. XA_PRIMARY).
+	*/
 	Atom				getSelection() const;
 
 	// IClipboard overrides
@@ -281,31 +305,54 @@ private:
 	Atom				m_atomGDKSelection;
 };
 
+//! Clipboard format converter interface
+/*!
+This interface defines the methods common to all X11 clipboard format
+converters.
+*/
 class IXWindowsClipboardConverter : public IInterface {
 public:
-	// accessors
+	//! @name accessors
+	//@{
 
-	// return the clipboard format this object converts from/to
+	//! Get clipboard format
+	/*!
+	Return the clipboard format this object converts from/to.
+	*/
 	virtual IClipboard::EFormat
 						getFormat() const = 0;
 
-	// return the atom representing the X selection format that
+	//! Get X11 format atom
-	// this object converts from/to
+	/*!
+	Return the atom representing the X selection format that
+	this object converts from/to.
+	*/
 	virtual Atom		getAtom() const = 0;
 
-	// return the size (in bits) of data elements returned by
+	//! Get X11 property datum size
-	// toIClipboard().
+	/*!
+	Return the size (in bits) of data elements returned by
+	toIClipboard().
+	*/
 	virtual int			getDataSize() const = 0;
 
-	// convert from the IClipboard format to the X selection format.
+	//! Convert from IClipboard format
-	// the input data must be in the IClipboard format returned by
+	/*!
-	// getFormat().  the return data will be in the X selection
+	Convert from the IClipboard format to the X selection format.
-	// format returned by getAtom().
+	The input data must be in the IClipboard format returned by
+	getFormat().  The return data will be in the X selection
+	format returned by getAtom().
+	*/
 	virtual CString		fromIClipboard(const CString&) const = 0;
 
-	// convert from the X selection format to the IClipboard format
+	//! Convert to IClipboard format
-	// (i.e., the reverse of fromIClipboard()).
+	/*!
+	Convert from the X selection format to the IClipboard format
+	(i.e., the reverse of fromIClipboard()).
+	*/
 	virtual CString		toIClipboard(const CString&) const = 0;
+
+	//@}
 };
 
 #endif

platform/CXWindowsClipboardTextConverter.h

@@ -3,8 +3,12 @@
 
 #include "CXWindowsClipboard.h"
 
+//! Convert to/from locale text encoding
 class CXWindowsClipboardTextConverter : public IXWindowsClipboardConverter {
 public:
+	/*!
+	\c name is converted to an atom and that is reported by getAtom().
+	*/
 	CXWindowsClipboardTextConverter(Display* display, const char* name);
 	virtual ~CXWindowsClipboardTextConverter();
 

platform/CXWindowsClipboardUCS2Converter.h

@@ -3,8 +3,12 @@
 
 #include "CXWindowsClipboard.h"
 
+//! Convert to/from UCS-2 encoding
 class CXWindowsClipboardUCS2Converter : public IXWindowsClipboardConverter {
 public:
+	/*!
+	\c name is converted to an atom and that is reported by getAtom().
+	*/
 	CXWindowsClipboardUCS2Converter(Display* display, const char* name);
 	virtual ~CXWindowsClipboardUCS2Converter();
 

platform/CXWindowsClipboardUTF8Converter.h

@@ -3,8 +3,12 @@
 
 #include "CXWindowsClipboard.h"
 
+//! Convert to/from UTF-8 encoding
 class CXWindowsClipboardUTF8Converter : public IXWindowsClipboardConverter {
 public:
+	/*!
+	\c name is converted to an atom and that is reported by getAtom().
+	*/
 	CXWindowsClipboardUTF8Converter(Display* display, const char* name);
 	virtual ~CXWindowsClipboardUTF8Converter();
 

platform/CXWindowsScreen.h

@@ -19,38 +19,62 @@ class IScreenReceiver;
 class CXWindowsClipboard;
 class CXWindowsScreenSaver;
 
+// X11 event
 class CEvent {
 public:
 	XEvent				m_event;
 	SInt32				m_result;
 };
 
+// X11 screen implementation
 class CXWindowsScreen : public IScreen {
 public:
 	CXWindowsScreen(IScreenReceiver*, IScreenEventHandler*);
 	virtual ~CXWindowsScreen();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// add/remove a job to invoke every timeout seconds.  the job is
+	//! Add timer
-	// called with the display locked.  if a job timeout expires twice
+	/*!
-	// or more before the job can be called then the job is called
+	Add a job to invoke every timeout seconds.  The job is
-	// just once.  the caller retains ownership of the job.
+	called with the display locked.  If a job timeout expires twice
+	or more before the job can be called then the job is called
+	just once.  The caller retains ownership of the job.
+	*/
 	void				addTimer(IJob*, double timeout);
+
+	//! Remove timer
+	/*!
+	Remove a job.  The caller retains ownership of the job.
+	*/
 	void				removeTimer(IJob*);
 
-	// set the window (created by the subclass).  this performs some
+	//! Set window
-	// initialization and saves the window in case it's needed later.
+	/*!
+	Set the window (created by the subclass).  This performs some
+	initialization and saves the window in case it's needed later.
+	*/
 	void				setWindow(Window);
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// get the root window of the screen
+	//! Get window
+	/*!
+	Returns the root window of the screen.
+	*/
 	Window				getRoot() const;
 
-	// get a cursor that is transparent everywhere
+	//! Get transparent cursor
+	/*!
+	Returns a cursor that is transparent everywhere.
+	*/
 	Cursor				getBlankCursor() const;
 
+	//@}
+
 	// IScreen overrides
 	void				open();
 	void				mainLoop();

platform/CXWindowsScreenSaver.h

@@ -12,6 +12,7 @@
 class IJob;
 class CXWindowsScreen;
 
+//! X11 screen saver implementation
 class CXWindowsScreenSaver : public IScreenSaver {
 public:
 	// note -- the caller must ensure that Display* passed to c'tor isn't
@@ -20,19 +21,30 @@ public:
 	CXWindowsScreenSaver(CXWindowsScreen*, Display*);
 	virtual ~CXWindowsScreenSaver();
 
-	// called for each event before event translation and dispatch.  return
+	//! @name manipulators
-	// true to skip translation and dispatch.  subclasses should call the
+	//@{
-	// superclass's version first and return true if it returns true.
+
+	//! Event filtering
+	/*!
+	Called for each event before event translation and dispatch.  Return
+	true to skip translation and dispatch.  Subclasses should call the
+	superclass's version first and return true if it returns true.
+	*/
 	bool				onPreDispatch(const XEvent*);
 
-	// tells this object to send a ClientMessage to the given window
+	//! Set notify target
-	// when the screen saver activates or deactivates.  only one
+	/*!
-	// window can be notified.  the message type is the "SCREENSAVER"
+	Tells this object to send a ClientMessage to the given window
-	// atom, the format is 32, and the data.l[0] member is non-zero
+	when the screen saver activates or deactivates.  Only one window
-	// if activated, zero if deactivated.  pass in None to disable
+	can be notified at a time.  The message type is the "SCREENSAVER"
-	// notification;
+	atom, the format is 32, and the data.l[0] member is non-zero
+	if activated, zero if deactivated.  Pass None to disable
+	notification.
+	*/
 	void				setNotify(Window);
 
+	//@}
+
 	// IScreenSaver overrides
 	virtual void		enable();
 	virtual void		disable();

platform/CXWindowsUtil.h

@@ -9,30 +9,67 @@
 #	include <X11/Xlib.h>
 #endif
 
+//! X11 utility functions
 class CXWindowsUtil {
 public:
+	//! Get property
+	/*!
+	Gets property \c property on \c window.  \b Appends the data to
+	\c *data if \c data is not NULL, saves the property type in \c *type
+	if \c type is not NULL, and saves the property format in \c *format
+	if \c format is not NULL.  If \c deleteProperty is true then the
+	property is deleted after being read.
+	*/
 	static bool			getWindowProperty(Display*,
 							Window window, Atom property,
 							CString* data, Atom* type,
 							SInt32* format, bool deleteProperty);
+
+	//! Set property
+	/*!
+	Sets property \c property on \c window to \c size bytes of data from
+	\c data.
+	*/
 	static bool			setWindowProperty(Display*,
 							Window window, Atom property,
 							const void* data, UInt32 size,
 							Atom type, SInt32 format);
+
+	//! Get X server time
+	/*!
+	Returns the current X server time.
+	*/
 	static Time			getCurrentTime(Display*, Window);
 
-	// class to set an X error handler in the c'tor and restore the
+	//! X11 error handler
-	// previous error handler in the d'tor.  a lock should only
+	/*!
-	// be installed while the display is locked by the thread.
+	This class sets an X error handler in the c'tor and restores the
-	//
+	previous error handler in the d'tor.  A lock should only be
-	// CErrorLock() ignores errors
+	installed while the display is locked by the thread.
-	// CErrorLock(bool* flag) sets *flag to true if any error occurs
+	
+	CErrorLock() ignores errors
+	CErrorLock(bool* flag) sets *flag to true if any error occurs
+	*/
 	class CErrorLock {
 	public:
+		//! Error handler type
 		typedef void (*ErrorHandler)(Display*, XErrorEvent*, void* userData);
+
+		/*!
+		Ignore X11 errors.
+		*/
 		CErrorLock(Display*);
+
+		/*!
+		Set \c *errorFlag if any error occurs.
+		*/
 		CErrorLock(Display*, bool* errorFlag);
-		CErrorLock(Display*, ErrorHandler, void* userData);
+
+		/*!
+		Call \c handler on each error.
+		*/
+		CErrorLock(Display*, ErrorHandler handler, void* userData);
+
 		~CErrorLock();
 
 	private:

platform/IMSWindowsScreenEventHandler.h

@@ -5,16 +5,26 @@
 #define WIN32_LEAN_AND_MEAN
 #include <windows.h>
 
+//! MS Windows screen event handler interface
 class IMSWindowsScreenEventHandler : public IScreenEventHandler {
 public:
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// called after the window is created
+	//! Notify of window creation
+	/*!
+	This is called after the window is created.
+	*/
 	virtual void		postCreateWindow(HWND) = 0;
 
-	// called before the window is destroyed
+	//! Notify of window destruction
+	/*!
+	This is called before the window is destroyed.
+	*/
 	virtual void		preDestroyWindow(HWND) = 0;
 
+	//@}
+
 	// IScreenEventHandler overrides
 	virtual void		onScreensaver(bool activated) = 0;
 	virtual bool		onPreDispatch(const CEvent* event) = 0;

platform/IPlatform.h

@@ -4,73 +4,110 @@
 #include "IInterface.h"
 #include "CString.h"
 
+//! Platform dependent functions interface
+/*!
+This interface provides methods to query platform specific data and
+perform operations that are inherently non-portable.
+*/
 class IPlatform : public IInterface {
 public:
 	typedef int			(*DaemonFunc)(IPlatform*, int argc, const char** argv);
 
+	//! Uninstall result codes
 	enum EResult {
-		kSuccess,
+		kSuccess,		//!< Uninstall succeeded
-		kFailed,
+		kFailed,		//!< Uninstall failed
-		kAlready
+		kAlready		//!< Not installed
 	};
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// install/uninstall a daemon.  commandLine should *not*
+	//! Install daemon
-	// include the name of program as the first argument.
+	/*!
+	Install a daemon.  \c name is the name of the daemon passed to the
+	system and \c description is a short human readable description of
+	the daemon.  \c pathname is the path to the daemon executable.
+	\c commandLine should \b not include the name of program as the
+	first argument.
+	*/
 	// FIXME -- throw on error?  will get better error messages that way.
 	virtual bool		installDaemon(const char* name,
 							const char* description,
 							const char* pathname,
 							const char* commandLine) = 0;
+	//! Uninstall daemon
+	/*!
+	Uninstall a daemon.
+	*/
 	virtual EResult		uninstallDaemon(const char* name) = 0;
 
-	// daemonize.  this should call installDaemonLogger().  returns
+	//! Daemonize the process
-	// true iff successful.  the name is the name of the daemon.
+	/*!
-
+	Daemonize.  This should call installDaemonLogger().  Returns
-	// daemonize.  this should have the side effect of sending log
+	true iff successful.  \c name is the name of the daemon.
-	// messages to a system message logger since messages can no
+	Once daemonized, \c func is invoked and daemonize returns when
-	// longer go to the console.  name is the name of the daemon.
+	and what it does.  daemonize() returns -1 on error.
-	// once daemonized, func is invoked and daemonize returns when
+	
-	// and what func does.  daemonize() returns -1 on error.
+	Exactly what happens when daemonizing depends on the platform.
-	//
+	<ul>
-	// exactly what happens when daemonizing depends on the platform.
+	<li>unix:
-	// unix:
+	  Detaches from terminal.  \c func gets passed one argument, the
-	//   detaches from terminal.  func gets one argument, the name
+	  name passed to daemonize().
-	//   passed to daemonize().
+	<li>win32:
-	// win32:
+	  Becomes a service.  Argument 0 is the name of the service
-	//   becomes a service.  argument 0 is the name of the service
+	  and the rest are the arguments passed to StartService().
-	//   and the rest are the arguments passed to StartService().
+	  \c func is only called when the service is actually started.
-	//   func is only called when the service is actually started.
+	  \c func must behave like a proper ServiceMain() function;  in
-	//   func must behave like a proper ServiceMain() function;  in
+	  particular, it must call RegisterServiceCtrlHandler() and
-	//   particular, it must call RegisterServiceCtrlHandler() and
+	  SetServiceStatus().
-	//   SetServiceStatus().
+	</ul>
+	*/
 	virtual int			daemonize(const char* name, DaemonFunc func) = 0;
 
-	// directs CLog to send messages to the daemon log.  used when
+	//! Install daemon logger
-	// messages should no longer go to the console.  name is used
+	/*!
-	// in the log to identify this process.
+	Directs CLog to send messages to the daemon log.  Used when
+	messages should no longer go to the console.  \c name is used
+	in the log to identify this process.
+	*/
 	virtual void		installDaemonLogger(const char* name) = 0;
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// find the basename in the given pathname
+	//! Extract base name
+	/*!
+	Find the base name in the given \c pathname.
+	*/
 	virtual const char*	getBasename(const char* pathname) const = 0;
 
-	// get the user's home directory.  returns the empty string if
+	//! Get user's home directory
-	// this cannot be determined.
+	/*!
+	Returns the user's home directory.  Returns the empty string if
+	this cannot be determined.
+	*/
 	virtual CString		getUserDirectory() const = 0;
 
-	// get the system configuration file directory
+	//! Get system directory
+	/*!
+	Returns the ussystem configuration file directory.
+	*/
 	virtual CString		getSystemDirectory() const = 0;
 
-	// concatenate pathname components with a directory separator
+	//! Concatenate path components
-	// between them.  this should not check if the resulting path
+	/*!
-	// is longer than allowed by the system.  we'll rely on the
+	Concatenate pathname components with a directory separator
-	// system calls to tell us that.
+	between them.  This should not check if the resulting path
+	is longer than allowed by the system;  we'll rely on the
+	system calls to tell us that.
+	*/
 	virtual CString		addPathComponent(
 							const CString& prefix,
 							const CString& suffix) const = 0;
+
+	//@}
 };
 
 #endif