add comment about syncType/syncState

app/coffee/RequestParser.coffee

@@ -31,10 +31,24 @@ module.exports = RequestParser =
 			response.check = @_parseAttribute "check",
 				compile.options.check,
 				type: "string"
+
+			# The syncType specifies whether the request contains all
+			# resources (full) or only those resources to be updated
+			# in-place (incremental).
 			response.syncType = @_parseAttribute "syncType",
 				compile.options.syncType,
 				validValues: ["full", "incremental"]
 				type: "string"
+
+			# The syncState is an identifier passed in with the request
+			# which has the property that it changes when any resource is
+			# added, deleted, moved or renamed.
+			#
+			# on syncType full the syncState identifier is passed in and
+			# stored
+			#
+			# on syncType incremental the syncState identifier must match
+			# the stored value
 			response.syncState = @_parseAttribute "syncState",
 				compile.options.syncState,
 				type: "string"

app/coffee/ResourceWriter.coffee

@@ -24,8 +24,23 @@ module.exports = ResourceWriter =
 				return callback(error) if error?
 				ResourceWriter.storeSyncState request.syncState, basePath, callback
 
+	# The sync state is an identifier which must match for an
+	# incremental update to be allowed.
+	#
+	# The initial value is passed in and stored on a full
+	# compile.
+	#
+	# Subsequent incremental compiles must come with the same value - if
+	# not they will be rejected with a 409 Conflict response.
+	#
+	# An incremental compile can only update existing files with new
+	# content.  The sync state identifier must change if any docs or
+	# files are moved, added, deleted or renamed.
+
+	SYNC_STATE_FILE: ".project-sync-state"
+
 	storeSyncState: (state, basePath, callback) ->
-		stateFile = Path.join(basePath, ".resource-sync-state")
+		stateFile = Path.join(basePath, @SYNC_STATE_FILE)
 		if not state? # remove the  file if no state passed in
 			logger.log state:state, basePath:basePath, "clearing sync state"
 			fs.unlink stateFile, (err) ->
@@ -38,10 +53,13 @@ module.exports = ResourceWriter =
 			fs.writeFile stateFile, state, {encoding: 'ascii'}, callback
 
 	checkSyncState: (state, basePath, callback) ->
-		stateFile = Path.join(basePath, ".resource-sync-state")
+		stateFile = Path.join(basePath, @SYNC_STATE_FILE)
 		fs.readFile stateFile, {encoding:'ascii'}, (err, oldState) ->
-			# ignore errors, return true if state matches, false otherwise (including errors)
+			if err? and err.code isnt 'ENOENT'
-			return callback(null, if state is oldState then true else false)
+				return callback(err)
+			else
+				# return true if state matches, false otherwise (including file not existing)
+				callback(null, if state is oldState then true else false)
 
 	saveIncrementalResourcesToDisk: (project_id, resources, basePath, callback = (error) ->) ->
 		@_createDirectory basePath, (error) =>