Added doxygen comments for all relevant headers in synergy.

synergy/CClipboard.h

@@ -1,35 +1,59 @@
 #ifndef CCLIPBOARD_H
 #define CCLIPBOARD_H
 
-//
-// CClipboard -- stores clipboard data in a memory buffer
-//
-
 #include "IClipboard.h"
 
+//! Memory buffer clipboard
+/*!
+This class implements a clipboard that stores data in memory.
+*/
 class CClipboard : public IClipboard {
 public:
 	CClipboard();
 	virtual ~CClipboard();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// unmarshall clipboard data
+	//! Unmarshall clipboard data
-	void				unmarshall(const CString& data, Time);
+	/*!
+	Extract marshalled clipboard data and store it in this clipboard.
+	Sets the clipboard time to \c time.
+	*/
+	void				unmarshall(const CString& data, Time time);
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// marshall clipboard data
+	//! Marshall clipboard data
+	/*!
+	Merge this clipboard's data into a single buffer that can be later
+	unmarshalled to restore the clipboard and return the buffer.
+	*/
 	CString				marshall() const;
 
-	// transfer all the data in one clipboard to another.  the
+	//! Copy clipboard
-	// clipboards can be of any concrete clipboard type (and
+	/*!
-	// they don't have to be the same type).  this also sets
+	Transfers all the data in one clipboard to another.  The
-	// the timestamp to time, if provided, or the time in src.
+	clipboards can be of any concrete clipboard type (and
-	// returns true iff the copy succeeded.
+	they don't have to be the same type).  This also sets
+	the destination clipboard's timestamp to source clipboard's
+	timestamp.  Returns true iff the copy succeeded.
+	*/
 	static bool			copy(IClipboard* dst, const IClipboard* src);
+
+	//! Copy clipboard
+	/*!
+	Transfers all the data in one clipboard to another.  The
+	clipboards can be of any concrete clipboard type (and they
+	don't have to be the same type).  This also sets the
+	timestamp to \c time.  Returns true iff the copy succeeded.
+	*/
 	static bool			copy(IClipboard* dst, const IClipboard* src, Time);
 
+	//@}
+
 	// IClipboard overrides
 	virtual bool		empty();
 	virtual void		add(EFormat, const CString& data);

synergy/CInputPacketStream.h

@@ -5,15 +5,15 @@
 #include "CBufferedInputStream.h"
 #include "CMutex.h"
 
+//! Packetizing input stream filter
+/*!
+Filters an input stream to extract packet by packet.
+*/
 class CInputPacketStream : public CInputStreamFilter {
 public:
 	CInputPacketStream(IInputStream*, bool adoptStream = true);
 	~CInputPacketStream();
 
-	// manipulators
-
-	// accessors
-
 	// IInputStream overrides
 	virtual void		close();
 	virtual UInt32		read(void*, UInt32 maxCount, double timeout);

synergy/COutputPacketStream.h

@@ -3,15 +3,16 @@
 
 #include "COutputStreamFilter.h"
 
+//! Packetizing output stream filter
+/*!
+Filters an output stream to create packets that include message
+boundaries.  Each write() is considered a single packet.
+*/
 class COutputPacketStream : public COutputStreamFilter {
 public:
 	COutputPacketStream(IOutputStream*, bool adoptStream = true);
 	~COutputPacketStream();
 
-	// manipulators
-
-	// accessors
-
 	// IOutputStream overrides
 	virtual void		close();
 	virtual UInt32		write(const void*, UInt32 count);

synergy/CProtocolUtil.h

@@ -8,32 +8,43 @@
 class IInputStream;
 class IOutputStream;
 
+//! Synergy protocol utilities
+/*!
+This class provides various functions for implementing the synergy
+protocol.
+*/
 class CProtocolUtil {
 public:
-	// write formatted binary data to a stream.  fmt consists of
+	//! Write formatted data
-	// regular characters and format specifiers.  format specifiers
+	/*!
-	// begin with %.  all characters not part of a format specifier
+	Write formatted binary data to a stream.  \c fmt consists of
-	// are regular and are transmitted unchanged.
+	regular characters and format specifiers.  Format specifiers
-	//
+	begin with \%.  All characters not part of a format specifier
-	// format specifiers are:
+	are regular and are transmitted unchanged.
-	//   %%   -- writes %
+	
-	//   %1i  -- converts integer argument to 1 byte integer
+	Format specifiers are:
-	//   %2i  -- converts integer argument to 2 byte integer in NBO
+	- \%\%   -- literal `\%'
-	//   %4i  -- converts integer argument to 4 byte integer in NBO
+	- \%1i  -- converts integer argument to 1 byte integer
-	//   %s   -- converts CString* to stream of bytes
+	- \%2i  -- converts integer argument to 2 byte integer in NBO
-	//   %S   -- converts integer N and const UInt8* to stream of N bytes
+	- \%4i  -- converts integer argument to 4 byte integer in NBO
+	- \%s   -- converts CString* to stream of bytes
+	- \%S   -- converts integer N and const UInt8* to stream of N bytes
+	*/
 	static void			writef(IOutputStream*,
 							const char* fmt, ...);
 
-	// read formatted binary data from a buffer.  this performs the
+	//! Read formatted data
-	// reverse operation of writef().
+	/*!
-	//
+	Read formatted binary data from a buffer.  This performs the
-	// format specifiers are:
+	reverse operation of writef().
-	//   %%   -- read (and discard) a %
+	
-	//   %1i  -- reads a 1 byte integer; argument is a SInt32* or UInt32*
+	Format specifiers are:
-	//   %2i  -- reads an NBO 2 byte integer;  arg is SInt32* or UInt32*
+	- \%\%   -- read (and discard) a literal `\%'
-	//   %4i  -- reads an NBO 4 byte integer;  arg is SInt32* or UInt32*
+	- \%1i  -- reads a 1 byte integer; argument is a SInt32* or UInt32*
-	//   %s   -- reads bytes;  argument must be a CString*, *not* a char*
+	- \%2i  -- reads an NBO 2 byte integer;  arg is SInt32* or UInt32*
+	- \%4i  -- reads an NBO 4 byte integer;  arg is SInt32* or UInt32*
+	- \%s   -- reads bytes;  argument must be a CString*, \b not a char*
+	*/
 	static void			readf(IInputStream*,
 							const char* fmt, ...);
 
@@ -44,6 +55,11 @@ private:
 	static void			read(IInputStream*, void*, UInt32);
 };
 
+//! Mismatched read exception
+/*!
+Thrown by CProtocolUtil::readf() when the data being read does not
+match the format.
+*/
 class XIOReadMismatch : public XIO {
 public:
 	// XBase overrides

synergy/CTCPSocketFactory.h

@@ -3,15 +3,12 @@
 
 #include "ISocketFactory.h"
 
+//! Socket factory for TCP sockets
 class CTCPSocketFactory : public ISocketFactory {
 public:
 	CTCPSocketFactory();
 	virtual ~CTCPSocketFactory();
 
-	// manipulators
-
-	// accessors
-
 	// ISocketFactory overrides
 	virtual IDataSocket*	create() const;
 	virtual IListenSocket*	createListen() const;

synergy/ClipboardTypes.h

@@ -3,9 +3,14 @@
 
 #include "BasicTypes.h"
 
-// type to hold a clipboard identifier
+//! Clipboard ID
+/*!
+Type to hold a clipboard identifier.
+*/
 typedef UInt8			ClipboardID;
 
+//! @name Clipboard identifiers
+//@{
 // clipboard identifiers.  kClipboardClipboard is what is normally
 // considered the clipboard (e.g. the cut/copy/paste menu items
 // affect it).  kClipboardSelection is the selection on those
@@ -17,5 +22,6 @@ static const ClipboardID	kClipboardSelection = 1;
 
 // the number of clipboards (i.e. one greater than the last clipboard id)
 static const ClipboardID	kClipboardEnd       = 2;
+//@}
 
 #endif

synergy/IClient.h

@@ -7,74 +7,171 @@
 #include "MouseTypes.h"
 #include "CString.h"
 
-// the client interface.  this provides all the methods necessary for
+//! Client interface
-// the server to communicate with a client.
+/*!
+This interface defines the methods necessary for the server to
+communicate with a client.
+*/
 class IClient : public IInterface {
 public:
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// open client.  return true iff successful.
+	//! Open client
+	/*!
+	Open the client and return true iff successful.
+	*/
 	virtual bool		open() = 0;
 
-	// service client
+	//! Run client
+	/*!
+	Service the client.  This method is typically called in a separate
+	thread and is exited by cancelling the thread.
+
+	(cancellation point)
+	*/
 	virtual void		run() = 0;
 
-	// close client
+	//! Close client
+	/*!
+	Close the client.
+	*/
 	virtual void		close() = 0;
 
-	// enter the screen.  the cursor should be warped to xAbs,yAbs.
+	//! Enter screen
-	// the client should record seqNum for future reporting of
+	/*!
-	// clipboard changes.  mask is the expected toggle button state.
+	Enter the screen.  The cursor should be warped to \c xAbs,yAbs.
-	// forScreensaver is true if the screen is being entered because
+	The client should record seqNum for future reporting of
-	// the screen saver is starting.
+	clipboard changes.  \c mask is the expected toggle button state
+	and the client should update its state to match.  \c forScreensaver
+	is true iff the screen is being entered because the screen saver is
+	starting.
+	*/
 	virtual void		enter(SInt32 xAbs, SInt32 yAbs,
 							UInt32 seqNum, KeyModifierMask mask,
 							bool forScreensaver) = 0;
 
-	// leave the screen.  returns false if the user may not leave the
+	//! Leave screen
-	// client's screen.
+	/*!
+	Leave the screen.  Return false iff the user may not leave the
+	client's screen (because, for example, a button is down).
+	*/
 	virtual bool		leave() = 0;
 
-	// update the client's clipboard.  this implies that the client's
+	//! Set clipboard
-	// clipboard is now up to date.  if the client's clipboard was
+	/*!
-	// already known to be up to date then this can do nothing.
+	Update the client's clipboard.  This implies that the client's
+	clipboard is now up to date.  If the client's clipboard was
+	already known to be up to date then this may do nothing.
+	*/
 	virtual void		setClipboard(ClipboardID, const CString&) = 0;
 
-	// grab the client's clipboard.  since this is called when another
+	//! Grab clipboard
-	// client takes ownership of the clipboard it implies that the
+	/*!
-	// client's clipboard is dirty.
+	Grab (i.e. take ownership of) the client's clipboard.  Since this
+	is called when another client takes ownership of the clipboard it
+	implies that the client's clipboard is out of date.
+	*/
 	virtual void		grabClipboard(ClipboardID) = 0;
 
-	// called to set the client's clipboard as dirty or clean
+	//! Mark clipboard dirty
+	/*!
+	Mark the client's clipboard as dirty (out of date) or clean (up to
+	date).
+	*/
 	virtual void		setClipboardDirty(ClipboardID, bool dirty) = 0;
 
-	// handle input events
+	//! Notify of key press
-	virtual void		keyDown(KeyID, KeyModifierMask) = 0;
+	/*!
-	virtual void		keyRepeat(KeyID, KeyModifierMask, SInt32 count) = 0;
+	Synthesize key events to generate a press of key \c id.  If possible
-	virtual void		keyUp(KeyID, KeyModifierMask) = 0;
+	match the given modifier mask.
-	virtual void		mouseDown(ButtonID) = 0;
+	*/
-	virtual void		mouseUp(ButtonID) = 0;
+	virtual void		keyDown(KeyID id, KeyModifierMask) = 0;
+
+	//! Notify of key repeat
+	/*!
+	Synthesize key events to generate a press and release of key \c id
+	\c count times.  If possible match the given modifier mask.
+	*/
+	virtual void		keyRepeat(KeyID id, KeyModifierMask, SInt32 count) = 0;
+
+	//! Notify of key release
+	/*!
+	Synthesize key events to generate a release of key \c id.  If possible
+	match the given modifier mask.
+	*/
+	virtual void		keyUp(KeyID id, KeyModifierMask) = 0;
+
+	//! Notify of mouse press
+	/*!
+	Synthesize mouse events to generate a press of mouse button \c id.
+	*/
+	virtual void		mouseDown(ButtonID id) = 0;
+
+	//! Notify of mouse release
+	/*!
+	Synthesize mouse events to generate a release of mouse button \c id.
+	*/
+	virtual void		mouseUp(ButtonID id) = 0;
+
+	//! Notify of mouse motion
+	/*!
+	Synthesize mouse events to generate mouse motion to the absolute
+	screen position \c xAbs,yAbs.
+	*/
 	virtual void		mouseMove(SInt32 xAbs, SInt32 yAbs) = 0;
+
+	//! Notify of mouse wheel motion
+	/*!
+	Synthesize mouse events to generate mouse wheel motion of \c delta.
+	\c delta is positive for motion away from the user and negative for
+	motion towards the user.  Each wheel click should generate a delta
+	of +/-120.
+	*/
 	virtual void		mouseWheel(SInt32 delta) = 0;
+
+	//! Notify of screen saver change
 	virtual void		screensaver(bool activate) = 0;
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// get the client's identifier
+	//! Get client name
+	/*!
+	Return the client's name.
+	*/
 	virtual CString		getName() const = 0;
 
-	// get the size of jump zone
+	//! Get jump zone size
+	/*!
+	Called to get the jump zone size.
+	*/
 	virtual SInt32		getJumpZoneSize() const = 0;
 
-	// get the screen's shape
+	//! Get screen shape
+	/*!
+	Return the position of the upper-left corner of the screen in \c x and
+	\c y and the size of the screen in \c w (width) and \c h (height).
+	*/
 	virtual void		getShape(SInt32& x, SInt32& y,
 							SInt32& width, SInt32& height) const = 0;
 
-	// get the mouse position
+	//! Get cursor position
+	/*!
+	Return the current position of the cursor in \c x and \c y.
+	*/
 	virtual void		getCursorPos(SInt32& x, SInt32& y) const = 0;
 
-	// get the center pixel
+	//! Get cursor center position
+	/*!
+	Return the cursor center position which is where we park the
+	cursor to compute cursor motion deltas and should be far from
+	the edges of the screen, typically the center.
+	*/
 	virtual void		getCursorCenter(SInt32& x, SInt32& y) const = 0;
+
+	//@}
 };
 
 #endif

synergy/IClipboard.h

@@ -5,61 +5,99 @@
 #include "CString.h"
 #include "BasicTypes.h"
 
+//! Clipboard interface
+/*!
+This interface defines the methods common to all clipboards.
+*/
 class IClipboard : public IInterface {
 public:
-	// timestamp type.  timestamps are in milliseconds from some
+	//! Timestamp type
-	// arbitrary starting time.  timestamps will wrap around to 0
+	/*!
-	// after about 49 3/4 days.
+	Timestamp type.  Timestamps are in milliseconds from some
+	arbitrary starting time.  Timestamps will wrap around to 0
+	after about 49 3/4 days.
+	*/
 	typedef UInt32 Time;
 
-	// known clipboard formats.  kNumFormats must be last and
+	//! Clipboard formats
-	// formats must be sequential starting from zero.  clipboard
+	/*!
-	// data set via add() and retrieved via get() is in one of
+	The list of known clipboard formats.  kNumFormats must be last and
-	// these formats.  platform dependent clipboard subclasses
+	formats must be sequential starting from zero.  Clipboard data set
-	// can and should present any suitable formats derivable
+	via add() and retrieved via get() must be in one of these formats.
-	// from these formats (e.g. UTF-16 encoded unicode).
+	Platform dependent clipboard subclasses can and should present any
-	//
+	suitable formats derivable from these formats.
-	// kText:  UTF-8 encoded unicode (ISO-10646), newline is LF.
+	*/
-	enum EFormat { kText, kNumFormats };
+	enum EFormat {
+		kText,			//!< Text format, UTF-8, newline is LF
+		kNumFormats		//!< The number of clipboard formats
+	};
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// take ownership of the clipboard and clear all data from it.
+	//! Empty clipboard
-	// must be called between an open() and close().  if returns
+	/*!
-	// false then the clipboard ownership could not be taken;  the
+	Take ownership of the clipboard and clear all data from it.
-	// clipboard should not be emptied in this case.
+	This must be called between a successful open() and close().
+	Return false if the clipboard ownership could not be taken;
+	the clipboard should not be emptied in this case.
+	*/
 	virtual bool		empty() = 0;
 
-	// add data in the given format to the clipboard.  data is
+	//! Add data
-	// passed as a string but the contents are generally not
+	/*!
-	// interpreted.  may only be called after a successful empty().
+	Add data in the given format to the clipboard.  May only be
+	called after a successful empty().
+	*/
 	virtual void		add(EFormat, const CString& data) = 0;
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// open the clipboard.  return true iff the clipboard could
+	//! Open clipboard
-	// be opened.  if open() returns true then it must be followed
+	/*!
-	// by a close() at some later time;  if it returns false then
+	Open the clipboard.  Return true iff the clipboard could be
-	// close() must not be called.
+	opened.  If open() returns true then the client must call
-	virtual bool		open(Time) const = 0;
+	close() at some later time;  if it returns false then close()
+	must not be called.  \c time should be the current time or
+	a time in the past when the open should effectively have taken
+	place.
+	*/
+	virtual bool		open(Time time) const = 0;
 
-	// close the clipboard.  close() must match a preceding open().
+	//! Close clipboard
-	// this signals that the clipboard has been filled with all the
+	/*!
-	// necessary data.  it does not mean the clipboard ownership
+	Close the clipboard.  close() must match a preceding successful
-	// should be released.
+	open().  This signals that the clipboard has been filled with
+	all the necessary data or all data has been read.  It does not
+	mean the clipboard ownership should be released (if it was
+	taken).
+	*/
 	virtual void		close() const = 0;
 
-	// returns the timestamp passed to the last successful open().
+	//! Get time
+	/*!
+	Return the timestamp passed to the last successful open().
+	*/
 	virtual Time		getTime() const = 0;
 
-	// returns true iff the clipboard contains data in the given
+	//! Check for data
-	// format.  must be called between an open() and close().
+	/*!
+	Return true iff the clipboard contains data in the given
+	format.  Must be called between a successful open() and close().
+	*/
 	virtual bool		has(EFormat) const = 0;
 
-	// returns data in the given format.  rturns the empty string
+	//! Get data
-	// if there is no data in that format.  must be called between
+	/*!
-	// an open() and close().
+	Return the data in the given format.  Returns the empty string
+	if there is no data in that format.  Must be called between
+	a successful open() and close().
+	*/
 	virtual CString		get(EFormat) const = 0;
+
+	//@}
 };
 
 #endif

synergy/IPrimaryScreenReceiver.h

@@ -5,24 +5,47 @@
 #include "KeyTypes.h"
 #include "MouseTypes.h"
 
-// the interface for receiving notification of events on the primary
+//! Primary screen event receiver interface
-// screen.  the server implements this interface to handle user input.
+/*!
-// platform dependent primary screen implementation will need to take
+The interface for receiving notification of events on the primary
-// an IPrimaryScreenReceiver* and notify it of events.
+screen.  The server implements this interface to handle user input.
+Platform dependent primary screen implementation will need to take
+an IPrimaryScreenReceiver* and notify it of events.
+*/
 class IPrimaryScreenReceiver : public IInterface {
 public:
-	// called when the screensaver is activated or deactivated
+	//! Notify of screen saver change
+	/*!
+	Called when the screensaver is activated or deactivated.
+	*/
 	virtual void		onScreensaver(bool activated) = 0;
 
 	// call to notify of events.  onMouseMovePrimary() returns
 	// true iff the mouse enters a jump zone and jumps.
+	//! Notify of key press
 	virtual void		onKeyDown(KeyID, KeyModifierMask) = 0;
+	//! Notify of key release
 	virtual void		onKeyUp(KeyID, KeyModifierMask) = 0;
+	//! Notify of key repeat
 	virtual void		onKeyRepeat(KeyID, KeyModifierMask, SInt32 count) = 0;
+	//! Notify of mouse button press
 	virtual void		onMouseDown(ButtonID) = 0;
+	//! Notify of mouse button release
 	virtual void		onMouseUp(ButtonID) = 0;
+	//! Notify of mouse motion
+	/*!
+	Called when the mouse has moved while on the primary screen.  \c x
+	and \c y are the absolute screen position of the mouse.  Return
+	true iff the mouse enters a jump zone and jumps.
+	*/
 	virtual bool		onMouseMovePrimary(SInt32 x, SInt32 y) = 0;
+	//! Notify of mouse motion
+	/*!
+	Called when the mouse has moved while on the secondary screen.
+	\c dx and \c dy are the relative motion from the last position.
+	*/
 	virtual void		onMouseMoveSecondary(SInt32 dx, SInt32 dy) = 0;
+	//! Notify of mouse wheen motion
 	virtual void		onMouseWheel(SInt32 delta) = 0;
 };
 

synergy/IScreen.h

@@ -6,65 +6,128 @@
 
 class IClipboard;
 
-// the interface for platform dependent screen implementations.  each
+//! Screen interface
-// platform will derive a type from IScreen for interaction with the
+/*!
-// platform's screen that's common to primary and secondary screens.
+This interface defines the methods common to all platform dependent
+screen implementations that are use by both primary and secondary
+screens.
+*/
 class IScreen : public IInterface {
 public:
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// open the screen
+	//! Open screen
+	/*!
+	Called to open and initialize the screen.
+	*/
 	virtual void		open() = 0;
 
-	// runs an event loop and returns when exitMainLoop() is called.
+	//! Run event loop
-	// must be called between open() and close().
+	/*!
+	Run the event loop and return when exitMainLoop() is called.
+	This must be called between a successful open() and close().
+	*/
 	virtual void		mainLoop() = 0;
 
-	// force mainLoop() to return
+	//! Exit event loop
+	/*!
+	Force mainLoop() to return.  This call can return before
+	mailLoop() does (i.e. asynchronously).
+	*/
 	virtual void		exitMainLoop() = 0;
 
-	// close the screen
+	//! Close screen
+	/*!
+	Called to close the screen.  close() should quietly ignore calls
+	that don't have a matching successful call to open().
+	*/
 	virtual void		close() = 0;
 
-	// set the contents of the clipboard
+	//! Set clipboard
-	virtual bool		setClipboard(ClipboardID, const IClipboard*) = 0;
+	/*!
+	Set the contents of the system clipboard indicated by \c id.
+	*/
+	virtual bool		setClipboard(ClipboardID id, const IClipboard*) = 0;
 
-	// check clipboard ownership and notify IScreenReceiver (set through
+	//! Check clipboard owner
-	// some other interface) if any changed
+	/*!
+	Check ownership of all clipboards and notify an IScreenReceiver (set
+	through some other interface) if any changed.  This is used as a
+	backup in case the system doesn't reliably report clipboard ownership
+	changes.
+	*/
 	virtual void		checkClipboards() = 0;
 
-	// open/close the screen saver.  if notify is true then this object
+	//! Open screen saver
-	// will call IScreenEventHandler's onScreenSaver() when the screensaver
+	/*!
-	// activates or deactivates until close.  if notify is false then
+	Open the screen saver.  If \c notify is true then this object must
-	// the screen saver is disabled on open and restored on close.
+	call an IScreenEventHandler's (set through some other interface)
+	onScreenSaver() when the screensaver activates or deactivates until
+	it's closed.  If \c notify is false then the screen saver is
+	disabled on open and restored on close.
+	*/
 	virtual void		openScreensaver(bool notify) = 0;
+
+	//! Close screen saver
+	/*!
+	// Close the screen saver.  Stop reporting screen saver activation
+	and deactivation and, if the screen saver was disabled by
+	openScreensaver(), enable the screen saver.
+	*/
 	virtual void		closeScreensaver() = 0;
 
-	// activate or deactivate the screen saver
+	//! Activate/deactivate screen saver
+	/*!
+	Forcibly activate the screen saver if \c activate is true otherwise
+	forcibly deactivate it.
+	*/
 	virtual void		screensaver(bool activate) = 0;
 
-	// ensure that this thread attached with the visible desktop.  this is
+	//! Attach to desktop
-	// mainly intended for windows which has an artificial distinction
+	/*!
-	// between desktops and a thread cannot interact with the visible
+	Called to ensure that this thread is attached to the visible desktop.
-	// desktop unless the thread is attached to that desktop.
+	This is mainly intended for microsoft windows which has an artificial
+	distinction between desktops where a thread cannot interact with the
+	visible desktop unless the thread is attached to that desktop.  Since
+	it doesn't report when the visible desktop changes we must poll.
+	*/
 	virtual void		syncDesktop() = 0;
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// get the contents of the clipboard
+	//! Get clipboard
-	virtual bool		getClipboard(ClipboardID, IClipboard*) const = 0;
+	/*!
+	Save the contents of the clipboard indicated by \c id and return
+	true iff successful.
+	*/
+	virtual bool		getClipboard(ClipboardID id, IClipboard*) const = 0;
 
-	// get the shape of the screen
+	//! Get screen shape
+	/*!
+	Return the position of the upper-left corner of the screen in \c x and
+	\c y and the size of the screen in \c w (width) and \c h (height).
+	*/
 	virtual void		getShape(SInt32& x, SInt32& y,
 							SInt32& w, SInt32& h) const = 0;
 
-	// get the current cursor coordinates
+	//! Get cursor position
+	/*!
+	Return the current position of the cursor in \c x and \c y.
+	*/
 	virtual void		getCursorPos(SInt32& x, SInt32& y) const = 0;
 
-	// get the cursor center position.  this is where we park the
+	//! Get cursor center position
-	// cursor to compute cursor motion deltas and should be far from
+	/*!
-	// the edges of the screen, typically the center.
+	Return the cursor center position which is where we park the
+	cursor to compute cursor motion deltas and should be far from
+	the edges of the screen, typically the center.
+	*/
 	virtual void		getCursorCenter(SInt32& x, SInt32& y) const = 0;
+
+	//@}
 };
 
 #endif

synergy/IScreenEventHandler.h

@@ -8,32 +8,52 @@ class CEvent;
 
 class IScreen;
 
-// the interface through which IScreen sends notification of events.
+//! Screen event handler interface
-// each platform will derive two types from IScreenEventHandler, one
+/*!
-// for handling events on the primary screen and one for the
+This is the interface through which IScreen sends notification of events.
-// secondary screen.  the header file with the IScreen subclass for
+Each platform will derive two types from IScreenEventHandler, one
-// each platform should define the CEvent type, which depends on the
+for handling events on the primary screen and one for the
-// type of native events for that platform.
+secondary screen.  The header file with the IScreen subclass for
+each platform should define the CEvent type, which depends on the
+type of native events for that platform.
+*/
 class IScreenEventHandler : public IInterface {
 public:
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// called when the screensaver is activated or deactivated
+	//! Notify of screen saver change
+	/*!
+	Called when the screensaver is activated or deactivated.
+	*/
 	virtual void		onScreensaver(bool activated) = 0;
 
-	// called for each event before event translation and dispatch.  return
+	//! Event filtering
-	// true to skip translation and dispatch.  subclasses should call the
+	/*!
-	// superclass's version first and return true if it returns true.
+	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.
+	*/
 	virtual bool		onPreDispatch(const CEvent* event) = 0;
 
-	// called by mainLoop().  iff the event was handled return true and
+	//! Event handling
-	// store the result, if any, in m_result, which defaults to zero.
+	/*!
+	Called to handle an event.  Iff the event was handled return true and
+	store the result, if any, in event->m_result, which defaults to zero.
+	*/
 	virtual bool		onEvent(CEvent* event) = 0;
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// called to get the jump zone size
+	//! Get jump zone size
+	/*!
+	Called to get the jump zone size.
+	*/
 	virtual SInt32		getJumpZoneSize() const = 0;
+
+	//@}
 };
 
 #endif

synergy/IScreenReceiver.h

@@ -6,23 +6,43 @@
 #include "ProtocolTypes.h"
 #include "CString.h"
 
-// the interface for types that receive screen resize and clipboard
+//! Screen event receiver interface
-// notifications (indirectly) from the system.
+/*!
+This interface defines the methods common to most types that receive
+events for changes to a screen.  Note that the methods in this
+interface are similar to the methods in IServer but have different
+parameters.  This interface is suitable for client-side types.
+*/
 class IScreenReceiver : public IInterface {
 public:
-	// called if the screen is unexpectedly closing.  this implies that
+	//! Notify of error
-	// the screen is no longer usable and that the program should
+	/*!
-	// close the screen and possibly terminate.
+	Called when the screen is unexpectedly closing.  This implies that
+	the screen is no longer usable and that the program should close
+	the screen and probably terminate.
+	*/
 	virtual void		onError() = 0;
 
-	// notify of client info change
+	//! Notify of client screen change
+	/*!
+	Called when the client's info has changed.  For example, when the
+	screen resolution has changed.
+	*/
 	virtual void		onInfoChanged(const CClientInfo&) = 0;
 
-	// notify of clipboard grab.  returns true if the grab was honored,
+	//! Notify of clipboad grab
-	// false otherwise.
+	/*!
+	Called when the clipboard was grabbed by another program and,
+	therefore, we no longer own it.  Returns true if the grab was
+	honored, false otherwise.
+	*/
 	virtual bool		onGrabClipboard(ClipboardID) = 0;
 
-	// notify of new clipboard data
+	//! Notify of new clipboard data
+	/*!
+	Called when the data on the clipboard has changed because some
+	other program has changed it.
+	*/
 	virtual void		onClipboardChanged(ClipboardID,
 							const CString& data) = 0;
 };

synergy/IScreenSaver.h

@@ -3,28 +3,57 @@
 
 #include "IInterface.h"
 
+//! Screen saver interface
+/*!
+This interface defines the methods common to all screen savers.
+*/
 class IScreenSaver : public IInterface {
 public:
 	// note -- the c'tor/d'tor must *not* enable/disable the screen saver
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// enable/disable the screen saver.  enable() should restore the
+	//! Enable screen saver
-	// screen saver settings to what they were when disable() was
+	/*!
-	// previously called.  if disable() wasn't previously called then
+	Enable the screen saver, restoring the screen saver settings to
-	// it should keep the current settings or use reasonable defaults.
+	what they were when disable() was previously called.  If disable()
+	wasn't previously called then it should keep the current settings
+	or use reasonable defaults.
+	*/
 	virtual void		enable() = 0;
+
+	//! Disable screen saver
+	/*!
+	Disable the screen saver, saving the old settings for the next
+	call to enable().
+	*/
 	virtual void		disable() = 0;
 
-	// activate/deactivate (i.e. show/hide) the screen saver.
+	//! Activate screen saver
-	// deactivate() also resets the screen saver timer.
+	/*!
+	Activate (i.e. show) the screen saver.
+	*/
 	virtual void		activate() = 0;
+
+	//! Deactivate screen saver
+	/*!
+	Deactivate (i.e. hide) the screen saver, reseting the screen saver
+	timer.
+	*/
 	virtual void		deactivate() = 0;
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// returns true iff the screen saver is active
+	//! Test if screen saver on
+	/*!
+	Returns true iff the screen saver is currently active (showing).
+	*/
 	virtual bool		isActive() const = 0;
+
+	//@}
 };
 
 #endif

synergy/IServer.h

@@ -7,33 +7,54 @@
 
 class CClientInfo;
 
-// the server interface.  this provides all the methods necessary for
+//! Server interface
-// clients to communicate with the server.  note that the methods
+/*!
-// in this interface are similar to the methods in IScreenReceiver but
+This interface defines the methods necessary for clients to
-// include extra parameters.  this interface is suitable for server-side
+communicate with the server.  Note that the methods in this
-// client proxies.  client-side objects should use the IScreenReceiver
+interface are similar to the methods in IScreenReceiver but
-// interface since the extra parameters are meaningless on the client-side.
+include extra parameters.  This interface is suitable for
+server-side client proxies.  Client-side objects should use
+the IScreenReceiver interface since the extra parameters are
+meaningless on the client-side.
+*/
 class IServer : public IInterface {
 public:
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// called if the screen is unexpectedly closing.  this implies that
+	//! Notify of error
-	// the screen is no longer usable and that the program should
+	/*!
-	// close the screen and possibly terminate.
+	Called when the screen is unexpectedly closing.  This implies that
+	the screen is no longer usable and that the program should close
+	the screen and probably terminate.
+	*/
 	virtual void		onError() = 0;
 
-	// notify of client info change
+	//! Notify of client screen change
+	/*!
+	Called when the client's info has changed.
+	*/
 	virtual void		onInfoChanged(const CString& clientName,
 							const CClientInfo&) = 0;
 
-	// notify of clipboard grab.  returns true if the grab was honored,
+	//! Notify of clipboad grab
-	// false otherwise.
+	/*!
+	Called when the clipboard was grabbed by another program and,
+	therefore, we no longer own it.  Returns true if the grab was
+	honored, false otherwise.
+	*/
 	virtual bool		onGrabClipboard(const CString& clientName,
 							ClipboardID, UInt32 seqNum) = 0;
 
-	// notify of new clipboard data
+	//! Notify of new clipboard data
+	/*!
+	Called when the data on the clipboard has changed because some
+	other program has changed it.
+	*/
 	virtual void		onClipboardChanged(ClipboardID,
 							UInt32 seqNum, const CString& data) = 0;
+
+	//@}
 };
 
 #endif

synergy/ISocketFactory.h

@@ -6,15 +6,23 @@
 class IDataSocket;
 class IListenSocket;
 
+//! Socket factory
+/*!
+This interface defines the methods common to all factories used to
+create sockets.
+*/
 class ISocketFactory : public IInterface {
 public:
-	// manipulators
+	//! @name accessors
+	//@{
 
-	// accessors
+	//! Create data socket
-
-	// create sockets
 	virtual IDataSocket*	create() const = 0;
+
+	//! Create listen socket
 	virtual IListenSocket*	createListen() const = 0;
+
+	//@}
 };
 
 #endif

synergy/KeyTypes.h

@@ -3,15 +3,22 @@
 
 #include "BasicTypes.h"
 
-// type to hold a key identifier.  the encoding is UTF-32, using
+//! Key ID
-// U+E000 through U+EFFF for the various control keys (e.g. arrow
+/*!
-// keys, function keys, modifier keys, etc).
+Type to hold a key identifier.  The encoding is UTF-32, using
+U+E000 through U+EFFF for the various control keys (e.g. arrow
+keys, function keys, modifier keys, etc).
+*/
 typedef UInt32			KeyID;
 
-// type to hold bitmask of key modifiers (e.g. shift keys)
+//! Modifier key ID
+/*!
+Type to hold a bitmask of key modifiers (e.g. shift keys).
+*/
 typedef UInt32			KeyModifierMask;
 
-// modifier key bitmasks
+//! @name Modifier key identifiers
+//@{
 static const KeyModifierMask	KeyModifierShift      = 0x0001;
 static const KeyModifierMask	KeyModifierControl    = 0x0002;
 static const KeyModifierMask	KeyModifierAlt        = 0x0004;
@@ -19,11 +26,12 @@ static const KeyModifierMask	KeyModifierMeta       = 0x0008;
 static const KeyModifierMask	KeyModifierCapsLock   = 0x1000;
 static const KeyModifierMask	KeyModifierNumLock    = 0x2000;
 static const KeyModifierMask	KeyModifierScrollLock = 0x4000;
+//@}
 
-//
+//! @name Key identifiers
-// key codes.  all codes except kKeyNone are equal to the corresponding
+//@{
+// all identifiers except kKeyNone are equal to the corresponding
 // X11 keysym - 0x1000.
-//
 
 // no key
 static const KeyID		kKeyNone		= 0x0000;
@@ -163,5 +171,6 @@ static const KeyID		kKeyHyper_R		= 0xEFEE;	/* Right hyper */
 
 // more function and modifier keys
 static const KeyID		kKeyLeftTab		= 0xEE20;
+//@}
 
 #endif

synergy/MouseTypes.h

@@ -3,13 +3,18 @@
 
 #include "BasicTypes.h"
 
-// type to hold mouse button identifier
+//! Mouse button ID
+/*!
+Type to hold a mouse button identifier.
+*/
 typedef UInt8			ButtonID;
 
-// mouse button identifiers
+//! @name Mouse button identifiers
+//@{
 static const ButtonID	kButtonNone   = 0;
 static const ButtonID	kButtonLeft   = 1;
 static const ButtonID	kButtonMiddle = 2;
 static const ButtonID	kButtonRight  = 3;
+//@}
 
 #endif

synergy/ProtocolTypes.h

@@ -3,11 +3,11 @@
 
 #include "BasicTypes.h"
 
-// version number
+// protocol version number
 static const SInt16		kProtocolMajorVersion = 0;
 static const SInt16		kProtocolMinorVersion = 7;
 
-// contact port number
+// default contact port number
 static const UInt16		kDefaultPort = 24800;
 
 // time between heartbeats (in seconds)
@@ -181,16 +181,37 @@ static const char		kMsgEBad[]			= "EBAD";
 // structures
 //
 
+//! Screen information
+/*!
+This class contains information about a screen.
+*/
 class CClientInfo {
 public:
-	// the coordinates of the screen 
+	//! Screen position
+	/*!
+	The position of the upper-left corner of the screen.  This is
+	typically 0,0.
+	*/
 	SInt32				m_x, m_y;
+
+	//! Screen size
+	/*!
+	The size of the screen in pixels.
+	*/
 	SInt32				m_w, m_h;
 
-	// the size of the jump zone
+	//! Jump zone size
+	/*!
+	This is the size of the jump zone.  The cursor jumps to the adjacent
+	screen when it comes within this many pixels of the edge of the screen.
+	*/
 	SInt32				m_zoneSize;
 
-	// mouse position
+	//! Mouse position
+	/*!
+	The position of the cursor.  This is not kept up-to-date so it's
+	only meaningful when receiving an update.
+	*/
 	SInt32				m_mx, m_my;
 };
 

synergy/Version.h

@@ -3,10 +3,12 @@
 
 #include "BasicTypes.h"
 
+// important strings
 static const char* kCopyright       = "Copyright (C) 2002 Chris Schoeneman";
-static const char* kContact         = "Chris Schoeneman crs23@bigfoot.com";
+static const char* kContact         = "Chris Schoeneman, crs23@bigfoot.com";
+static const char* kWebsite         = "";
 
-// build version.  follows linux kernel style:  minor number even implies
+// build version.  follows linux kernel style:  an even minor number implies
 // a release version, odd implies development version.
 static const SInt16 kMajorVersion   = 0;
 static const SInt16 kMinorVersion   = 9;

synergy/XScreen.h

@@ -3,9 +3,13 @@
 
 #include "XBase.h"
 
+//! Generic screen exception
 class XScreen : public XBase { };
 
-// screen cannot be opened
+//! Cannot open screen exception
+/*!
+Thrown when a screen cannot be opened or initialized.
+*/
 class XScreenOpenFailure : public XScreen {
 protected:
 	virtual CString		getWhat() const throw();

synergy/XSynergy.h

@@ -3,26 +3,36 @@
 
 #include "XBase.h"
 
+//! Generic synergy exception
 class XSynergy : public XBase { };
 
-// client is misbehaving
+//! Client error exception
+/*!
+Thrown when the client fails to follow the protocol.
+*/
 class XBadClient : public XSynergy {
 protected:
 	virtual CString		getWhat() const throw();
 };
 
-// client has incompatible version
+//! Incompatible client exception
+/*!
+Thrown when a client attempting to connect has an incompatible version.
+*/
 class XIncompatibleClient : public XSynergy {
 public:
 	XIncompatibleClient(int major, int minor);
 
-	// manipulators
+	//! @name accessors
-
+	//@{
-	// accessors
 
+	//! Get client's major version number
 	int					getMajor() const throw();
+	//! Get client's minor version number
 	int					getMinor() const throw();
 
+	//@}
+
 protected:
 	virtual CString		getWhat() const throw();
 
@@ -31,18 +41,24 @@ private:
 	int					m_minor;
 };
 
-// client has duplicate name (i.e. client with name is already connected)
+//! Client already connected exception
+/*!
+Thrown when a client attempting to connect is using the same name as
+a client that is already connected.
+*/
 class XDuplicateClient : public XSynergy {
 public:
 	XDuplicateClient(const CString& name);
 
-	// manipulators
+	//! @name accessors
-
+	//@{
-	// accessors
 
+	//! Get client's name
 	virtual const CString&
 						getName() const throw();
 
+	//@}
+
 protected:
 	virtual CString		getWhat() const throw();
 
@@ -50,18 +66,24 @@ private:
 	CString				m_name;
 };
 
-// client has unknown name (i.e. name is not in server's screen map)
+//! Client not in map
+/*!
+Thrown when a client attempting to connect is using a name that is
+unknown to the server.
+*/
 class XUnknownClient : public XSynergy {
 public:
 	XUnknownClient(const CString& name);
 
-	// manipulators
+	//! @name accessors
-
+	//@{
-	// accessors
 
+	//! Get the client's name
 	virtual const CString&
 						getName() const throw();
 
+	//@}
+
 protected:
 	virtual CString		getWhat() const throw();