Added doxygen comments for all relevant headers in client and server.

client/CClient.h

@@ -13,31 +13,57 @@ class CThread;
 class IDataSocket;
 class IScreenReceiver;
 
+//! Synergy client
+/*!
+This class implements the top-level client algorithms for synergy.
+*/
 class CClient : public IScreenReceiver, public IClient {
 public:
+	/*!
+	This client will attempt to connect the server using \c clientName
+	as its name.
+	*/
 	CClient(const CString& clientName);
 	~CClient();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// turn camping on or off.  when camping the client will keep
+	//! Set camping state
-	// trying to connect to the server until it succeeds.  this
+	/*!
-	// is useful if the client may start before the server.  do
+	Turns camping on or off.  When camping the client will keep
-	// not call this while in run().
+	trying to connect to the server until it succeeds.  This
+	is useful if the client may start before the server.  Do
+	not call this while in run().
+	*/
 	void				camp(bool on);
 
-	// set the server's address that the client should connect to
+	//! Set server address
+	/*!
+	Sets the server's address that the client should connect to.
+	*/
 	void				setAddress(const CNetworkAddress& serverAddress);
 
-	// tell client to exit run() gracefully.  this must only be called
+	//! Exit event loop
-	// after a successful open().
+	/*!
+	Force run() to return.  This call can return before
+	run() does (i.e. asynchronously).  This may only be
+	called between a successful open() and close().
+	*/
 	void				quit();
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// returns true if the server rejected us
+	//!
+	/*!
+	Returns true if the server rejected our connection.
+	*/
 	bool 				wasRejected() const;
 
+	//@}
+
 	// IScreenReceiver overrides
 	virtual void		onError();
 	virtual void		onInfoChanged(const CClientInfo&);

client/CMSWindowsSecondaryScreen.h

@@ -16,6 +16,7 @@
 class CMSWindowsScreen;
 class IScreenReceiver;
 
+//! Microsoft windows secondary screen implementation
 class CMSWindowsSecondaryScreen :
 				public CSecondaryScreen, public IMSWindowsScreenEventHandler {
 public:

client/CSecondaryScreen.h

@@ -9,126 +9,305 @@
 class IClipboard;
 class IScreen;
 
-// platform independent base class for secondary screen implementations.
+//! Generic client-side screen
-// each platform will derive a class from CSecondaryScreen to handle
+/*!
-// platform dependent operations.
+This is a platform independent base class for secondary screen
+implementations.  A secondary screen is a client-side screen.
+Each platform will derive a class from CSecondaryScreen to handle
+platform dependent operations.
+*/
 class CSecondaryScreen {
 public:
 	CSecondaryScreen();
 	virtual ~CSecondaryScreen();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// enter the screen's message loop.  this returns when it detects
+	//! Open screen
-	// the application should terminate or when stop() is called.
+	/*!
-	// run() may only be called between open() and close().
+	Opens the screen.  This includes initializing the screen,
-	void				run();
+	hiding the cursor, and disabling the screen saver.  It also causes
-
+	events to the reported to an IScreenReceiver (which is set through
-	// cause run() to return
+	some other interface).  Calls close() before returning (rethrowing)
-	void				stop();
+	if it fails for any reason.
-
+	*/
-	// initialize the screen, hide the cursor, and disable the screen
-	// saver.  start reporting events to the IScreenReceiver (which is
-	// set through some other interface).
 	void				open();
 
-	// close the screen.  should restore the screen saver.  it should
+	//! Run event loop
-	// also simulate key up events for any keys that have simulate key
+	/*!
-	// down events without a matching key up.  without this the client
+	Run the screen's event loop.  This returns when it detects
-	// will leave its keyboard in the wrong logical state.
+	the application should terminate or when stop() is called.
+	run() may only be called between open() and close().
+	*/
+	void				run();
+
+	//! Exit event loop
+	/*!
+	Force run() to return.  This call can return before
+	run() does (i.e. asynchronously).
+	*/
+	void				stop();
+
+	//! Close screen
+	/*!
+	Closes the screen.  This restores the screen saver, shows the cursor
+	and closes the screen.  It also synthesizes key up events for any
+	keys that are logically down;  without this the client will leave
+	its keyboard in the wrong logical state.
+	*/
 	void				close();
 
-	// called when the user navigates to this secondary screen.  warps
+	//! Enter screen
-	// the cursor to the given absoltue coordinates and unhide it.  prepare to
+	/*!
-	// simulate input events.
+	Called when the user navigates to this secondary screen.  Warps
+	the cursor to the absolute coordinates \c x,y and unhides
+	it.  Also prepares to synthesize input events.
+	*/
 	void				enter(SInt32 x, SInt32 y, KeyModifierMask mask);
 
-	// called when the user navigates off the secondary screen.  clean
+	//! Leave screen
-	// up input event simulation and hide the cursor.
+	/*!
+	Called when the user navigates off the secondary screen.  Cleans
+	up input event synthesis and hides the cursor.
+	*/
 	void				leave();
 
-	// set the screen's clipboard contents.  this is usually called
+	//! Set clipboard
-	// soon after an enter().
+	/*!
+	Sets the system's clipboard contents.  This is usually called
+	soon after an enter().
+	*/
 	void				setClipboard(ClipboardID, const IClipboard*);
 
-	// synergy should own the clipboard
+	//! Grab clipboard
+	/*!
+	Grabs (i.e. take ownership of) the system clipboard.
+	*/
 	void				grabClipboard(ClipboardID);
 
-	// activate or deactivate the screen saver
+	//! Activate/deactivate screen saver
+	/*!
+	Forcibly activates the screen saver if \c activate is true otherwise
+	forcibly deactivates it.
+	*/
 	void				screensaver(bool activate);
 
-	// keyboard input event synthesis
+	//! 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		keyDown(KeyID id, KeyModifierMask) = 0;
 
-	// mouse input event synthesis
+	//! Notify of key repeat
-	virtual void		mouseDown(ButtonID) = 0;
+	/*!
-	virtual void		mouseUp(ButtonID) = 0;
+	Synthesize key events to generate a press and release of key \c id
-	virtual void		mouseMove(SInt32 xAbsolute, SInt32 yAbsolute) = 0;
+	\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;
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// returns true iff the screen is active (i.e. the user has entered
+	//! Test if active
-	// the screen)
+	/*!
+	Returns true iff the screen is active (i.e. the user has entered
+	the screen).  Note this is the reverse of a primary screen.
+	*/
 	bool				isActive() const;
 
-	// return the contents of the given clipboard
+	//! Get clipboard
-	void				getClipboard(ClipboardID, IClipboard*) const;
+	/*!
+	Saves the contents of the system clipboard indicated by \c id.
+	*/
+	void				getClipboard(ClipboardID id, IClipboard*) const;
 
-	// returns the size of the zone on the edges of the screen that
+	//! Get jump zone size
-	// causes the cursor to jump to another screen.
+	/*!
+	Return the jump zone size, the size of the regions on the edges of
+	the screen that cause the cursor to jump to another screen.
+	*/
 	virtual SInt32		getJumpZoneSize() const = 0;
 
-	// get the shape (position of upper-left corner and size) of the
+	//! Get screen shape
-	// screen
+	/*!
+	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 width and \c height.
+	*/
 	virtual void		getShape(SInt32& x, SInt32& y,
 							SInt32& width, SInt32& height) const;
 
-	// get the position of the mouse on the screen
+	//! Get cursor position
+	/*!
+	Return the current position of the cursor in \c x,y.
+	*/
 	virtual void		getCursorPos(SInt32& x, SInt32& y) const;
 
-	// get the platform dependent screen object
+	//! Get screen
+	/*!
+	Return the platform dependent screen.
+	*/
 	virtual IScreen*	getScreen() const = 0;
 
+	//@}
+
 protected:
-	// template method hooks.  these are called on entry/exit to the
+	//! Pre-run() hook
-	// named method.  override to do platform specific operations.
+	/*!
-	// defaults do nothing.
+	Called on entry to run().  Override to perform platform specific
+	operations.  Default does nothing.  May throw.
+	*/
 	virtual void		onPreRun();
+
+	//! Post-run() hook
+	/*!
+	Called on exit from run().  Override to perform platform specific
+	operations.  Default does nothing.  May \b not throw.
+	*/
 	virtual void		onPostRun();
+
+	//! Pre-open() hook
+	/*!
+	Called on entry to open().  Override to perform platform specific
+	operations.  Default does nothing.  May throw.
+	*/
 	virtual void		onPreOpen();
+
+	//! Post-open() hook
+	/*!
+	Called on exit from open() iff the open was successful.  Default
+	does nothing.  May throw.
+	*/
 	virtual void		onPostOpen();
+
+	//! Pre-close() hook
+	/*!
+	Called on entry to close().  Override to perform platform specific
+	operations.  Default does nothing.  May \b not throw.
+	*/
 	virtual void		onPreClose();
+
+	//! Post-close() hook
+	/*!
+	Called on exit from close().  Override to perform platform specific
+	operations.  Default does nothing.  May \b not throw.
+	*/
 	virtual void		onPostClose();
+
+	//! Pre-enter() hook
+	/*!
+	Called on entry to enter() after desktop synchronization.  Override
+	to perform platform specific operations.  Default does nothing.  May
+	\b not throw.
+	*/
 	virtual void		onPreEnter();
+
+	//! Post-enter() hook
+	/*!
+	Called on exit from enter().  Override to perform platform specific
+	operations.  Default does nothing.  May \b not throw.
+	*/
 	virtual void		onPostEnter();
+
+	//! Pre-leave() hook
+	/*!
+	Called on entry to leave() after desktop synchronization.  Override
+	to perform platform specific operations.  Default does nothing.  May
+	\b not throw.
+	*/
 	virtual void		onPreLeave();
+
+	//! Post-leave() hook
+	/*!
+	Called on exit from leave().  Override to perform platform specific
+	operations.  Default does nothing.  May \b not throw.
+	*/
 	virtual void		onPostLeave();
 
-	// create/destroy the window.  this window is generally used to
+	//! Create window
-	// receive events and hide the cursor.
+	/*!
+	Called to create the window.  This window is generally used to
+	receive events and hide the cursor.
+	*/
 	virtual void		createWindow() = 0;
+
+	//! Destroy window
+	/*!
+	Called to destroy the window created by createWindow().
+	*/
 	virtual void		destroyWindow() = 0;
 
-	// called when the user navigates off the secondary screen.  hide
+	//! Show window
-	// the cursor.
+	/*!
+	Called when the user navigates off this secondary screen.  It needn't
+	actually show the window created by createWindow() but it must hide
+	the cursor and clean up event synthesis.
+	*/
 	virtual void		showWindow() = 0;
 
-	// called when the user navigates to this secondary screen.  show
+	//! Hide window
-	// the cursor and prepare to synthesize input events.
+	/*!
+	Called when the user navigates to this secondary screen.  It should
+	hide the window (if shown), show the cursor, and prepare to synthesize
+	input events.
+	*/
 	virtual void		hideWindow() = 0;
 
-	// warp the cursor to the given absolute coordinates
+	//! Warp cursor
+	/*!
+	Warp the cursor to the absolute coordinates \c x,y.
+	*/
 	virtual void		warpCursor(SInt32 x, SInt32 y) = 0;
 
-	// check the current keyboard state.  normally a screen will save
+	//! Synchronize key state
-	// the keyboard state in this method and use this shadow state
+	/*!
-	// when synthesizing events.
+	Check the current keyboard state.  Normally a screen will save
+	the keyboard state in this method and use this shadow state
+	when synthesizing events.
+	*/
 	virtual void		updateKeys() = 0;
 
-	// toggle modifiers that don't match the given state
+	//! Synchronize toggle key state
+	/*!
+	Toggle modifiers that don't match the given state so that they do.
+	*/
 	virtual void		setToggleState(KeyModifierMask) = 0;
 
 private:

client/CServerProxy.cpp

@@ -15,10 +15,10 @@
 //
 
 CServerProxy::CServerProxy(IClient* client,
-				IInputStream* input, IOutputStream* output) :
+				IInputStream* adoptedInput, IOutputStream* adoptedOutput) :
 	m_client(client),
-	m_input(input),
+	m_input(adoptedInput),
-	m_output(output),
+	m_output(adoptedOutput),
 	m_seqNum(0)
 {
 	assert(m_client != NULL);

client/CServerProxy.h

@@ -8,31 +8,60 @@ class IClient;
 class IInputStream;
 class IOutputStream;
 
+//! Proxy for server
+/*!
+This class acts a proxy for the server, converting calls into messages
+to the server and messages from the server to calls on the client.
+*/
 class CServerProxy : public IScreenReceiver {
 public:
+	/*! \c adoptedInput is the stream from the server and
+	\c adoptedOutput is the stream to the server.  This object
+	takes ownership of both and destroys them in the d'tor.
+	Messages from the server are converted to calls on \c client.
+	*/
 	CServerProxy(IClient* client,
 							IInputStream* adoptedInput,
 							IOutputStream* adoptedOutput);
 	~CServerProxy();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// handle messages.  returns true iff server didn't reject our
+	//! Run event loop
-	// connection.
+	/*!
+	Run the event loop and return when the server disconnects or
+	requests the client to disconnect.  Return true iff the server
+	didn't reject our connection.
+
+	(cancellation point)
+	*/
 	bool				run();
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// get the client
+	//! Get client
+	/*!
+	Returns the client passed to the c'tor.
+	*/
 	IClient*			getClient() const;
 
-	// get the client name
+	//! Get input stream
-	CString				getName() const;
+	/*!
-
+	Return the input stream passed to the c'tor.
-	// get the input and output streams for the server
+	*/
 	IInputStream*		getInputStream() const;
+
+	//! Get output stream
+	/*!
+	Return the output stream passed to the c'tor.
+	*/
 	IOutputStream*		getOutputStream() const;
 
+	//@}
+
 	// IScreenReceiver overrides
 	virtual void		onError();
 	virtual void		onInfoChanged(const CClientInfo&);
@@ -40,6 +69,10 @@ public:
 	virtual void		onClipboardChanged(ClipboardID, const CString& data);
 
 private:
+
+	// get the client name (from the client)
+	CString				getName() const;
+
 	// if compressing mouse motion then send the last motion now
 	void				flushCompressedMouse();
 

client/CXWindowsSecondaryScreen.h

@@ -14,6 +14,7 @@
 class CXWindowsScreen;
 class IScreenReceiver;
 
+//! X11 secondary screen implementation
 class CXWindowsSecondaryScreen :
 				public CSecondaryScreen, public IScreenEventHandler {
 public:

server/CClientProxy.h

@@ -8,24 +8,40 @@ class IInputStream;
 class IOutputStream;
 class IServer;
 
+//! Generic proxy for client
 class CClientProxy : public IClient {
 public:
+	/*!
+	\c name is the name of the client.
+	*/
 	CClientProxy(IServer* server, const CString& name,
 							IInputStream* adoptedInput,
 							IOutputStream* adoptedOutput);
 	~CClientProxy();
 
-	// manipulators
+	//! @name accessors
+	//@{
 
-	// accessors
+	//! Get server
-
+	/*!
-	// get the server
+	Returns the server passed to the c'tor.
+	*/
 	IServer*			getServer() const;
 
-	// get the input and output streams for the client
+	//! Get input stream
+	/*!
+	Returns the input stream passed to the c'tor.
+	*/
 	IInputStream*		getInputStream() const;
+
+	//! Get output stream
+	/*!
+	Returns the output stream passed to the c'tor.
+	*/
 	IOutputStream*		getOutputStream() const;
 
+	//@}
+
 	// IClient overrides
 	virtual bool		open() = 0;
 	virtual void		run() = 0;

server/CClientProxy1_0.h

@@ -5,6 +5,7 @@
 #include "ProtocolTypes.h"
 #include "CMutex.h"
 
+//! Proxy for client implementing protocol version 1.0
 class CClientProxy1_0 : public CClientProxy {
 public:
 	CClientProxy1_0(IServer* server, const CString& name,

server/CConfig.h

@@ -20,6 +20,16 @@ struct iterator_traits<CConfig> {
 };
 };
 
+//! Server configuration
+/*!
+This class holds server configuration information.  That includes
+the names of screens and their aliases, the links between them,
+and network addresses.
+
+Note that case is preserved in screen names but is ignored when
+comparing names.  Screen names and their aliases share a
+namespace and must be unique.
+*/
 class CConfig {
 private:
 	class CCell {
@@ -59,79 +69,155 @@ public:
 	CConfig();
 	virtual ~CConfig();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// note that case is preserved in screen names but is ignored when
+	//! Add screen
-	// comparing names.  screen names and their aliases share a
+	/*!
-	// namespace and must be unique.
+	Adds a screen, returning true iff successful.  If a screen or
-
+	alias with the given name exists then it fails.
-	// add/remove screens.  addScreen() returns false if the name
+	*/
-	// already exists.  the remove methods automatically remove
-	// aliases for the named screen and disconnect any connections
-	// to the removed screen(s).
 	bool				addScreen(const CString& name);
+
+	//! Remove screen
+	/*!
+	Removes a screen.  This also removes aliases for the screen and
+	disconnects any connections to the screen.  \c name may be an
+	alias.
+	*/
 	void				removeScreen(const CString& name);
+
+	//! Remove all screens
+	/*!
+	Removes all screens, aliases, and connections.
+	*/
 	void				removeAllScreens();
 
-	// add/remove alias for a screen name.  an alias can be used
+	//! Add alias
-	// any place the canonical screen name can (except addScreen).
+	/*!
-	// addAlias() returns false if the alias name already exists
+	Adds an alias for a screen name.  An alias can be used
-	// or the canonical name is unknown.  removeAlias() fails if
+	any place the canonical screen name can (except addScreen()).
-	// the alias is unknown or a canonical name.
+	Returns false if the alias name already exists or the canonical
+	name is unknown, otherwise returns true.
+	*/
 	bool				addAlias(const CString& canonical,
 							const CString& alias);
+
+	//! Remove alias
+	/*!
+	Removes an alias for a screen name.  It returns false if the
+	alias is unknown or a canonical name, otherwise returns true.
+	*/
 	bool				removeAlias(const CString& alias);
+
+	//! Remove all aliases
+	/*!
+	This removes all aliases but not the screens.
+	*/
 	void				removeAllAliases();
 
-	// connect/disconnect edges.  both return false if srcName is
+	//! Connect screens
-	// unknown.
+	/*!
+	Establishes a one-way connection between opposite edges of two
+	screens.  The user will be able to jump from the \c srcSide of
+	screen \c srcName to the opposite side of screen \c dstName
+	when both screens are connected to the server and the user
+	isn't locked to a screen.  Returns false if \c srcName is
+	unknown.
+	*/
 	bool				connect(const CString& srcName,
 							EDirection srcSide,
 							const CString& dstName);
+
+	//! Disconnect screens
+	/*!
+	Removes a connection created by connect().  Returns false if
+	\c srcName is unknown.
+	*/
 	bool				disconnect(const CString& srcName,
 							EDirection srcSide);
 
-	// set the synergy and http listen addresses.  there are no
+	//! Set server address
-	// default addresses.
+	/*!
+	Set the synergy listen addresses.  There is no default address so
+	this must be called to run a server using this configuration.
+	*/
 	void				setSynergyAddress(const CNetworkAddress&);
+
+	//! Set HTTP server address
+	/*!
+	Set the HTTP listen addresses.  There is no default address so
+	this must be called to run an HTTP server using this configuration.
+	*/
 	void				setHTTPAddress(const CNetworkAddress&);
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// returns true iff the given name is a valid screen name.
+	//! Test screen name validity
-	bool				isValidScreenName(const CString&) const;
+	/*!
+	Returns true iff \c name is a valid screen name.
+	*/
+	bool				isValidScreenName(const CString& name) const;
 
-	// iterators over (canonical) screen names
+	//! Get beginning (canonical) screen name iterator
 	const_iterator		begin() const;
+	//! Get ending (canonical) screen name iterator
 	const_iterator		end() const;
 
-	// returns true iff name names a screen
+	//! Test for screen name
+	/*!
+	Returns true iff \c name names a screen.
+	*/
 	bool				isScreen(const CString& name) const;
 
-	// returns true iff name is the canonical name of a screen
+	//! Test for canonical screen name
+	/*!
+	Returns true iff \c name is the canonical name of a screen.
+	*/
 	bool				isCanonicalName(const CString& name) const;
 
-	// returns the canonical name of a screen or the empty string if
+	//! Get canonical name
-	// the name is unknown.  returns the canonical name if one is given.
+	/*!
+	Returns the canonical name of a screen or the empty string if
+	the name is unknown.  Returns the canonical name if one is given.
+	*/
 	CString				getCanonicalName(const CString& name) const;
 
-	// get the neighbor in the given direction.  returns the empty string
+	//! Get neighbor
-	// if there is no neighbor in that direction.  returns the canonical
+	/*!
-	// screen name.
+	Returns the canonical screen name of the neighbor in the given
+	direction (set through connect()).  Returns the empty string
+	if there is no neighbor in that direction.
+	*/
 	CString				getNeighbor(const CString&, EDirection) const;
 
-	// get the listen addresses
+	//! Get the server address
 	const CNetworkAddress&	getSynergyAddress() const;
+	//! Get the HTTP server address
 	const CNetworkAddress&	getHTTPAddress() const;
 
-	// read/write a configuration.  operator>> will throw XConfigRead
+	//! Read configuration
-	// on error.
+	/*!
+	Reads a configuration from a stream.  Throws XConfigRead on error.
+	*/
 	friend std::istream&	operator>>(std::istream&, CConfig&);
+
+	//! Write configuration
+	/*!
+	Writes a configuration to a stream.
+	*/
 	friend std::ostream&	operator<<(std::ostream&, const CConfig&);
 
-	// get the name of a direction (for debugging)
+	//! Get direction name
+	/*!
+	Returns the name of a direction (for debugging).
+	*/
 	static const char*	dirName(EDirection);
 
+	//@}
+
 private:
 	static bool			readLine(std::istream&, CString&);
 	void				readSection(std::istream&);
@@ -149,6 +235,10 @@ private:
 	CNetworkAddress		m_httpAddress;
 };
 
+//! Configuration stream read exception
+/*!
+Thrown when a configuration stream cannot be parsed.
+*/
 class XConfigRead : public XBase {
 public:
 	XConfigRead(const CString&);

server/CHTTPServer.cpp

@@ -53,8 +53,15 @@ CHTTPServer::processRequest(IDataSocket* socket)
 			request->m_uri = request->m_uri.substr(n);
 		}
 
-		// process
+		// prepare reply
 		CHTTPReply reply;
+		reply.m_majorVersion = request->m_majorVersion;
+		reply.m_minorVersion = request->m_minorVersion;
+		reply.m_status       = 200;
+		reply.m_reason       = "OK";
+		reply.m_method       = request->m_method;
+
+		// process
 		doProcessRequest(*request, reply);
 
 		// send reply
@@ -93,21 +100,19 @@ CHTTPServer::processRequest(IDataSocket* socket)
 void
 CHTTPServer::doProcessRequest(CHTTPRequest& request, CHTTPReply& reply)
 {
-	reply.m_majorVersion = request.m_majorVersion;
-	reply.m_minorVersion = request.m_minorVersion;
-	reply.m_status       = 200;
-	reply.m_reason       = "OK";
-	reply.m_method       = request.m_method;
-	reply.m_headers.push_back(std::make_pair(CString("Content-Type"),
-											CString("text/html")));
-
 	// switch based on uri
 	if (request.m_uri == "/editmap") {
 		if (request.m_method == "GET" || request.m_method == "HEAD") {
 			doProcessGetEditMap(request, reply);
+			reply.m_headers.push_back(std::make_pair(
+								CString("Content-Type"),
+									CString("text/html")));
 		}
 		else if (request.m_method == "POST") {
 			doProcessPostEditMap(request, reply);
+			reply.m_headers.push_back(std::make_pair(
+								CString("Content-Type"),
+									CString("text/html")));
 		}
 		else {
 			throw XHTTPAllow("GET, HEAD, POST");

server/CHTTPServer.h

@@ -11,26 +11,52 @@ class CHTTPRequest;
 class CHTTPReply;
 class IDataSocket;
 
+//! Simple HTTP server
+/*!
+This class implements a simple HTTP server for interacting with the
+synergy server.
+*/
 class CHTTPServer {
 public:
 	CHTTPServer(CServer*);
 	virtual ~CHTTPServer();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// synchronously process an HTTP request on the given socket
+	//! Process HTTP request
+	/*!
+	Synchronously processes an HTTP request on the given socket.
+	*/
 	void				processRequest(IDataSocket*);
 
-	// accessors
+	//@}
 
 protected:
+	//! Process HTTP request
+	/*!
+	Processes a successfully read HTTP request.  The reply is partially
+	filled in (version, method, status (200) and reason (OK)).  This
+	method checks the URI and handles the request, filling in the rest
+	of the reply.  If the request cannot be satisfied it throws an
+	appropriate XHTTP exception.
+	*/
 	virtual void		doProcessRequest(CHTTPRequest&, CHTTPReply&);
 
+	//! Process request for map
 	virtual void		doProcessGetEditMap(CHTTPRequest&, CHTTPReply&);
+
+	//! Process request for changing map
 	virtual void		doProcessPostEditMap(CHTTPRequest&, CHTTPReply&);
 
+	//! Parse coordinate string
 	static bool			parseXY(const CString&, SInt32& x, SInt32& y);
 
+	//! Screen map helper
+	/*!
+	This class represents the screen map as a resizable array.  It's
+	used to handle map requests.
+	*/
 	class CScreenArray {
 	public:
 		CScreenArray();

server/CMSWindowsPrimaryScreen.h

@@ -11,6 +11,7 @@ class CMSWindowsScreen;
 class IScreenReceiver;
 class IPrimaryScreenReceiver;
 
+//! Microsoft windows primary screen implementation
 class CMSWindowsPrimaryScreen :
 				public CPrimaryScreen, public IMSWindowsScreenEventHandler {
 public:

server/CPrimaryClient.h

@@ -10,29 +10,60 @@ class CPrimaryScreen;
 class IPrimaryScreenReceiver;
 class IServer;
 
+//! Primary screen as pseudo-client
+/*!
+The primary screen does not have a client associated with it.  This
+class provides a pseudo-client to allow the primary screen to be
+treated as if it was on a client.
+*/
 class CPrimaryClient : public IScreenReceiver, public IClient {
 public:
+	/*!
+	\c name is the name of the server.
+	*/
 	CPrimaryClient(IServer*, IPrimaryScreenReceiver*, const CString& name);
 	~CPrimaryClient();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// cause run() to return
+	//! Exit event loop
+	/*!
+	Force run() to return.  This call can return before
+	run() does (i.e. asynchronously).  This may only be
+	called between a successful open() and close().
+	*/
 	void				stop();
 
-	// called by server when the configuration changes
+	//! Update configuration
+	/*!
+	Handles reconfiguration of jump zones.
+	*/
 	void				reconfigure(UInt32 activeSides);
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// return the contents of the given clipboard.
+	//! Get clipboard
+	/*!
+	Save the marshalled contents of the clipboard indicated by \c id.
+	*/
 	void				getClipboard(ClipboardID, CString&) const;
 
-	// returns true iff the user is locked to the primary screen
+	//! Get toggle key state
+	/*!
+	Returns the primary screen's current toggle modifier key state.
+	*/
+	KeyModifierMask		getToggleMask() const;
+
+	//! Get screen lock state
+	/*!
+	Returns true if the user is locked to the screen.
+	*/
 	bool				isLockedToScreen() const;
 
-	// returns the state of the toggle keys on the primary screen
+	//@}
-	KeyModifierMask		getToggleMask() const;
 
 	// IScreenReceiver overrides
 	virtual void		onError();

server/CPrimaryScreen.h

@@ -9,140 +9,291 @@ class IClipboard;
 class IScreen;
 class IScreenReceiver;
 
-// platform independent base class for primary screen implementations.
+//! Generic server-side screen
-// each platform will derive a class from CPrimaryScreen to handle
+/*!
-// platform dependent operations.
+This is a platform independent base class for primary screen
+implementations.  A primary screen is a server-side screen.
+Each platform will derive a class from CPrimaryScreen to handle
+platform dependent operations.
+*/
 class CPrimaryScreen {
 public:
 	CPrimaryScreen(IScreenReceiver*);
 	virtual ~CPrimaryScreen();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// enter the screen's message loop.  this returns when it detects
+	//! Open screen
-	// the application should terminate or when stop() is called.
+	/*!
-	// run() may only be called between open() and close().
+	Opens the screen.  This includes initializing the screen, opening
-	void				run();
+	the screen saver, synchronizing keyboard state, and causing events
-
+	to be reported to an IPrimaryScreenReceiver (set through another
-	// cause run() to return
+	interface).  Calls close() before returning (rethrowing) if it
-	void				stop();
+	fails for any reason.
-
+	*/
-	// initializes the screen and starts reporting events
 	void				open();
 
-	// close the screen
+	//! Run event loop
+	/*!
+	Run the screen's event loop.  This returns when it detects
+	the application should terminate or when stop() is called.
+	run() may only be called between open() and close().
+	*/
+	void				run();
+
+	//! Exit event loop
+	/*!
+	Force run() to return.  This call can return before
+	run() does (i.e. asynchronously).
+	*/
+	void				stop();
+
+	//! Close screen
+	/*!
+	Closes the screen.  This close the screen saver and the screen.
+	*/
 	void				close();
 
-	// called when the user navigates to the primary screen.
+	//! Enter screen
-	// forScreensaver == true means that we're entering the primary
+	/*!
-	// screen because the screensaver has activated.
+	Called when the user navigates to the primary screen.  Warps
+	the cursor to the absolute coordinates \c x,y and unhides
+	it.  If \c forScreensaver is true then we're entering because
+	the screen saver started and the cursor is not warped.
+	*/
 	void				enter(SInt32 x, SInt32 y, bool forScreensaver);
 
-	// called when the user navigates off the primary screen.  returns
+	//! Leave screen
-	// true iff successful.
+	/*!
+	Called when the user navigates off the primary screen.  Returns
+	true iff successful.
+	*/
 	bool				leave();
 
-	// called when the configuration has changed.  activeSides is a
+	//! Update configuration
-	// bitmask of EDirectionMask indicating which sides of the
+	/*!
-	// primary screen are linked to clients.
+	This is called when the configuration has changed.  \c activeSides
+	is a bitmask of EDirectionMask indicating which sides of the
+	primary screen are linked to clients.  Override to handle the
+	possible change in jump zones.
+	*/
 	virtual void		reconfigure(UInt32 activeSides) = 0;
 
-	// warp the cursor to the given absolute coordinates.  also
+	//! Warp cursor
-	// discard input events up to and including the warp before
+	/*!
-	// returning.
+	Warp the cursor to the absolute coordinates \c x,y.  Also
+	discard input events up to and including the warp before
+	returning.
+	*/
 	virtual void		warpCursor(SInt32 x, SInt32 y) = 0;
 
-	// set the screen's clipboard contents.  this is usually called
+	//! Set clipboard
-	// soon after an enter().
+	/*!
+	Sets the system's clipboard contents.  This is usually called
+	soon after an enter().
+	*/
 	void				setClipboard(ClipboardID, const IClipboard*);
 
-	// synergy should own the clipboard
+	//! Grab clipboard
+	/*!
+	Grabs (i.e. take ownership of) the system clipboard.
+	*/
 	void				grabClipboard(ClipboardID);
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// returns true iff the screen is active (i.e. the user has left
+	//! Test if active
-	// the screen)
+	/*!
+	Returns true iff the screen is active (i.e. the user has left
+	the screen).  Note this is the reverse of a secdonary screen.
+	*/
 	bool				isActive() const;
 
-	// return the contents of the given clipboard
+	//! Get clipboard
+	/*!
+	Saves the contents of the system clipboard indicated by \c id.
+	*/
 	void				getClipboard(ClipboardID, IClipboard*) const;
 
-	// returns the size of the zone on the edges of the screen that
+	//! Get jump zone size
-	// causes the cursor to jump to another screen.
+	/*!
+	Return the jump zone size, the size of the regions on the edges of
+	the screen that cause the cursor to jump to another screen.
+	*/
 	virtual SInt32		getJumpZoneSize() const = 0;
 
-	// get the primary screen's current toggle modifier key state.
+	//! Get toggle key state
-	// the returned mask should have the corresponding bit set for
+	/*!
-	// each toggle key that is active.
+	Return the primary screen's current toggle modifier key state.
+	The returned mask should have the corresponding bit set for
+	each toggle key that is active.  For example, if caps lock is
+	on then the returned mask should have \c KeyModifierCapsLock set.
+	*/
 	virtual KeyModifierMask	getToggleMask() const = 0;
 
-	// return true if any key or button is being pressed or if there's
+	//! Get screen lock state
-	// any other reason that the user should not be allowed to switch
+	/*!
-	// screens.
+	Return true if any key or button is being pressed or if there's
+	any other reason that the user should not be allowed to switch
+	screens.  Active toggle keys (including the scroll lock key)
+	should not be counted as reasons to lock to the screen.
+	*/
 	virtual bool		isLockedToScreen() const = 0;
 
-	// get the platform dependent screen object
+	//! Get screen
+	/*!
+	Return the platform dependent screen.
+	*/
 	virtual IScreen*	getScreen() const = 0;
 
+	//@}
+
 protected:
-	// template method hooks.  these are called on entry/exit to the
+	//! Pre-run() hook
-	// named method.  onEnterScreensaver() is called by enter() iff
+	/*!
-	// forScreensaver is true.  onPostLeave() is passed the result of
+	Called on entry to run().  Override to perform platform specific
-	// showWindow().  override to do platform specific operations.
+	operations.  Default does nothing.  May throw.
-	// defaults do nothing.
+	*/
 	virtual void		onPreRun();
+
+	//! Post-run() hook
+	/*!
+	Called on exit from run().  Override to perform platform specific
+	operations.  Default does nothing.  May \b not throw.
+	*/
 	virtual void		onPostRun();
+
+	//! Pre-open() hook
+	/*!
+	Called on entry to open().  Override to perform platform specific
+	operations.  Default does nothing.  May throw.
+	*/
 	virtual void		onPreOpen();
+
+	//! Post-open() hook
+	/*!
+	Called on exit from open() iff the open was successful.  Default
+	does nothing.  May throw.
+	*/
 	virtual void		onPostOpen();
+
+	//! Pre-close() hook
+	/*!
+	Called on entry to close().  Override to perform platform specific
+	operations.  Default does nothing.  May \b not throw.
+	*/
 	virtual void		onPreClose();
+
+	//! Post-close() hook
+	/*!
+	Called on exit from close().  Override to perform platform specific
+	operations.  Default does nothing.  May \b not throw.
+	*/
 	virtual void		onPostClose();
+
+	//! Pre-enter() hook
+	/*!
+	Called from enter() after the cursor has been warped or, if
+	\c forScreensaver is true, onEnterScreensaver() was called.  Override
+	to perform platform specific operations.  Default does nothing.  May
+	\b not throw.
+	*/
 	virtual void		onPreEnter();
+
+	//! Post-enter() hook
+	/*!
+	Called on exit from enter().  Override to perform platform specific
+	operations.  Default does nothing.  May \b not throw.
+	*/
 	virtual void		onPostEnter();
+
+	//! Pre-enter() for screen saver hook
+	/*!
+	Called on entry to enter() if the \c forScreensaver passed to it was
+	true.  Override to perform platform specific operations.  Default
+	does nothing.  May \b not throw.
+	*/
 	virtual void		onEnterScreensaver();
+
+	//! Pre-leave() hook
+	/*!
+	Called on entry to leave() after desktop synchronization.  Override
+	to perform platform specific operations.  Default does nothing.  May
+	\b not throw.
+	*/
 	virtual void		onPreLeave();
+
+	//! Post-leave() hook
+	/*!
+	Called on exit from leave().  \c success is the value returned by
+	showWindow().  Override to perform platform specific operations.
+	Default does nothing.  May \b not throw.
+	*/
 	virtual void		onPostLeave(bool success);
 
-	// create/destroy the window.  this window is generally used to
+	//! Create window
-	// receive events and, when the user navigates to another screen,
+	/*!
-	// to capture keyboard and mouse input.
+	Called to create the window.  This window is generally used to
+	receive events, hide the cursor, and to capture keyboard and mouse
+	input.
+	*/
 	virtual void		createWindow() = 0;
+
+	//! Destroy window
+	/*!
+	Called to destroy the window created by createWindow().
+	*/
 	virtual void		destroyWindow() = 0;
 
-	// called when the user navigates off the primary screen.  hide the
+	//! Show window
-	// cursor and grab exclusive access to the input devices.  returns
+	/*!
-	// true iff successful.  every call to showWindow() has a matching
+	Called when the user navigates off the primary screen.  Hide the
-	// call to hideWindow() which preceeds it.  return true iff
+	cursor and grab exclusive access to the input devices.  Every call
-	// successful (in particular, iff the input devices were grabbed).
+	to showWindow() has a matching call to hideWindow() which preceeds
-	//
+	it.  Return true iff successful (in particular, iff the input
-	// after a successful showWindow(), user input events and
+	devices were grabbed).
-	// screensaver activation/deactivation should be reported to an
+	
-	// IPrimaryScreenReceiver until hideWindow() is called.  report
+	After a successful showWindow(), user input events and
-	// mouse motion to IPrimaryScreenReceiver::onMouseMoveSecondary().
+	screensaver activation/deactivation should be reported to an
-	// user input should not be delivered to any application except
+	IPrimaryScreenReceiver (set through another interface) until
-	// synergy.
+	hideWindow() is called.  Report mouse motion to its
+	onMouseMoveSecondary().  User input should not be delivered to
+	any application except this one.
+	*/
 	virtual bool		showWindow() = 0;
 
-	// called when the user navigates back to the primary screen.  show
+	//! Hide window
-	// the cursor and ungab the input devices.
+	/*!
-	//
+	Called when the user navigates back to the primary screen.  Show
-	// after hideWindow(), user input events should be delivered normally.
+	the cursor and ungrab the input devices.
-	// mouse motion over (at least) the jump zones must be reported to
+	
-	// an IPrimaryScreenReceiver::onMouseMovePrimary().
+	After hideWindow(), user input events should be delivered normally
+	to other applications.  Mouse motion over (at least) the jump zones
+	must be reported to an IPrimaryScreenReceiver's onMouseMovePrimary().
+	*/
 	virtual void		hideWindow() = 0;
 
-	// prepare the cursor to report relative motion.  when the user has
+	//! Warp cursor for relative motion
-	// navigated to another screen, synergy requires the cursor motion
+	/*!
-	// deltas, not the absolute coordinates.  typically this is done by
+	Prepare the cursor to report relative motion.  When the user has
-	// warping the cursor to the center of the primary screen and then
+	navigated to another screen, synergy requires the cursor motion
-	// every time it moves compute the motion and warp back to the
+	deltas, not the absolute coordinates.  Typically this is done by
-	// center (but without reporting that warp as motion).  this is
+	warping the cursor to the center of the primary screen and then
-	// only called after a successful showWindow().
+	every time it moves compute the motion and warp back to the
+	center (but without reporting that warp as motion).  This is
+	only called after a successful showWindow().
+	*/
 	virtual void		warpCursorToCenter() = 0;
 
-	// check the current keyboard state.  normally a screen will save
+	//! Synchronize key state
-	// the keyboard state in this method and use this shadow state
+	/*!
-	// when handling user input and in methods like isLockedToScreen().
+	Check the current keyboard state.  Normally a screen will save
+	the keyboard state in this method and use this shadow state
+	when handling user input and in methods like isLockedToScreen().
+	*/
 	virtual void		updateKeys() = 0;
 
 private:

server/CServer.h

@@ -20,39 +20,77 @@ class IServerProtocol;
 class ISocketFactory;
 class ISecurityFactory;
 
+//! Synergy server
+/*!
+This class implements the top-level server algorithms for synergy.
+*/
 class CServer : public IServer, public IPrimaryScreenReceiver {
 public:
+	/*!
+	The server will look itself up in the configuration using \c serverName
+	as its name.
+	*/
 	CServer(const CString& serverName);
 	~CServer();
 
-	// manipulators
+	//! @name manipulators
+	//@{
 
-	// open the server's screen
+	//! Open server
+	/*!
+	Open the server and return true iff successful.
+	*/
 	bool				open();
 
-	// start the server.  does not return until quit() is called.
+	//! Server main loop
-	// this must be preceeded by a successful call to open().
+	/*!
+	Run server's event loop and return when quit() is called.
+	This must be called between a successful open() and close().
+
+	(cancellation point)
+	*/
 	void				run();
 
-	// tell server to exit gracefully.  this may only be called
+	//! Exit event loop
-	// after a successful open().
+	/*!
+	Force run() to return.  This call can return before
+	run() does (i.e. asynchronously).  This may only be
+	called between a successful open() and close().
+	*/
 	void				quit();
 
-	// close the server's screen
+	//! Close server
+	/*!
+	Close the server.
+	*/
 	void				close();
 
-	// update screen map.  returns true iff the new configuration was
+	//! Set configuration
-	// accepted.
+	/*!
+	Change the server's configuration.  Returns true iff the new
+	configuration was accepted (it must include the server's name).
+	This will disconnect any clients no longer in the configuration.
+	*/
 	bool				setConfig(const CConfig&);
 
-	// accessors
+	//@}
+	//! @name accessors
+	//@{
 
-	// get the current screen map
+	//! Get configuration
+	/*!
+	Returns the current configuration.
+	*/
 	void				getConfig(CConfig*) const;
 
-	// get the primary screen's name
+	//! Get name
+	/*!
+	Returns the server's name passed to the c'tor
+	*/
 	CString				getPrimaryScreenName() const;
 
+	//@}
+
 	// IServer overrides
 	virtual void		onError();
 	virtual void		onInfoChanged(const CString&, const CClientInfo&);
@@ -71,6 +109,10 @@ public:
 	virtual void		onMouseWheel(SInt32 delta);
 
 protected:
+	//! Handle special keys
+	/*!
+	Handles keys with special meaning.
+	*/
 	bool				onCommandKey(KeyID, KeyModifierMask, bool down);
 
 private:

server/CXWindowsPrimaryScreen.h

@@ -14,6 +14,7 @@ class CXWindowsScreen;
 class IScreenReceiver;
 class IPrimaryScreenReceiver;
 
+//! X11 primary screen implementation
 class CXWindowsPrimaryScreen :
 				public CPrimaryScreen, public IScreenEventHandler {
 public:

synergy/IClient.h

@@ -23,10 +23,11 @@ public:
 	*/
 	virtual bool		open() = 0;
 
-	//! Run client
+	//! Client main loop
 	/*!
-	Service the client.  This method is typically called in a separate
+	Run client's event loop.  This method is typically called in a
-	thread and is exited by cancelling the thread.
+	separate thread and is exited by cancelling the thread.  This
+	must be called between a successful open() and close().
 
 	(cancellation point)
 	*/
@@ -62,9 +63,10 @@ public:
 	/*!
 	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.
+	already known to be up to date then this may do nothing.  \c data
+	has marshalled clipboard data.
 	*/
-	virtual void		setClipboard(ClipboardID, const CString&) = 0;
+	virtual void		setClipboard(ClipboardID, const CString& data) = 0;
 
 	//! Grab clipboard
 	/*!
@@ -152,7 +154,7 @@ public:
 	//! 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).
+	\c y and the size of the screen in \c width and \c height.
 	*/
 	virtual void		getShape(SInt32& x, SInt32& y,
 							SInt32& width, SInt32& height) const = 0;

synergy/IScreen.h

@@ -33,7 +33,8 @@ public:
 	//! Exit event loop
 	/*!
 	Force mainLoop() to return.  This call can return before
-	mailLoop() does (i.e. asynchronously).
+	mainLoop() does (i.e. asynchronously).  This may only be
+	called between a successful open() and close().
 	*/
 	virtual void		exitMainLoop() = 0;
 

synergy/IScreenReceiver.h

@@ -41,7 +41,8 @@ public:
 	//! Notify of new clipboard data
 	/*!
 	Called when the data on the clipboard has changed because some
-	other program has changed it.
+	other program has changed it.  \c data will have marshalled
+	clipboard data.
 	*/
 	virtual void		onClipboardChanged(ClipboardID,
 							const CString& data) = 0;

synergy/IServer.h

@@ -49,7 +49,8 @@ public:
 	//! Notify of new clipboard data
 	/*!
 	Called when the data on the clipboard has changed because some
-	other program has changed it.
+	other program has changed it.  \c data has the marshalled clipboard
+	data.
 	*/
 	virtual void		onClipboardChanged(ClipboardID,
 							UInt32 seqNum, const CString& data) = 0;