improve comments

doc/design/external_special_remote_protocol.mdwn

@@ -98,8 +98,7 @@ The following requests *must* all be supported by the special remote.
   Requests the transfer of a key. For Send, the File is the file to upload;
   for Receive the File is where to store the download.  
   Note that the File should not influence the filename used on the remote.
-  The filename used should be derived from the Key, and will not contain
-  any whitespace.  
+  The filename will not contain any whitespace.  
   Multiple transfers might be requested by git-annex, but it's fine for the 
   program to serialize them and only do one at a time.
 * `CHECKPRESENT Key`  

doc/special_remotes/external/example.sh

@@ -52,9 +52,14 @@ while read line; do
 		INITREMOTE)
 			# Do anything necessary to create resources
 			# used by the remote. Try to be idempotent.
+			# 
 			# Use GETCONFIG to get any needed configuration
 			# settings, and SETCONFIG to set any persistent
 			# configuration settings.
+			# 
+			# (Note that this is not run every time, only when
+			# git annex initremote or git annex enableremote is
+			# run.)
 			getconfig directory
 			mydirectory="$RET"
 			if [ -z "$mydirectory" ]; then
@@ -91,7 +96,7 @@ while read line; do
 				RETRIEVE)
 					# Retrieve from a location based on
 					# the key, outputting to the file.
-					# XXX when easy, send PROGRESS
+					# XXX when easy to do, send PROGRESS
 					calclocation "$key"
 					if runcmd cp -v "$LOC" "$file"; then
 						echo TRANSFER-SUCCESS RETRIEVE "$key"
@@ -110,7 +115,7 @@ while read line; do
 				if [ -d "$mydirectory" ]; then
 					echo CHECKPRESENT-FAILURE "$key"
 				else
-					# If the directory does not exist,
+					# When the directory does not exist,
 					# the remote is not available.
 					# (A network remote would similarly
 					# fail with CHECKPRESENT-UNKNOWN