Add comments to the upload script code

upload/upload.sh

@@ -61,24 +61,33 @@ elif [[ -z ${ACCESS_TOKEN} ]]; then
 	exit 1
 fi
 
+# check out all supplied positional arguments, and separate them into lists
+# of metadata-only records and records with files, for later processing
 record_dirs=()
 record_files=()
 while [[ $# -gt 0 ]]; do
 	record=$1
 	if [[ -f ${record} ]]; then
+		# if the argument points to a JSON file, treat it as metadata-only record
 		jq . ${record} > /dev/null
+
 		if [[ $? -eq 0 ]]; then
 			record_files+=( ${record} )
 		else
 			echo "not a valid json file: ${record}/metadata.json" 1>&2
 		fi
+
 	elif [[ -d ${record} && -f ${record}/metadata.json ]]; then
+		# if the argument points to a directory containing 'metadata.json',
+		# treat it as record with files
 		jq . ${record}/metadata.json > /dev/null
+
 		if [[ $? -eq 0 ]]; then
 			record_dirs+=( ${record} )
 		else
 			echo "not a valid json file: ${record}/metadata.json" 1>&2
 		fi
+
 	else
 		echo "unknown entity: ${record}" 1>&2
 	fi
@@ -95,7 +104,10 @@ auth_header="Authorization: Bearer ${ACCESS_TOKEN}"
 json_header="Content-Type: application/json"
 octet_header="Content-Type: application/octet-stream"
 recids=()
+
+# upload the collected records with files
 for record in ${record_dirs[@]}; do
+	# create a new draft, with the specified metadata
 	recid=$(curl -sk -X POST -H "${json_header}" -H "${auth_header}" -d @${record}/metadata.json ${base_url}/api/records | jq ".id")
 	recid=${recid%\"}
 	recid=${recid#\"}
@@ -104,11 +116,17 @@ for record in ${record_dirs[@]}; do
 	files=()
 	file_objects=""
 	if [[ -d ${record}/files ]]; then
+		# check out the content of the 'files/' subdirectory, and collect information
+		# about the contained files (which are going to be uploaded)
+
 		for file in ${record}/files/*; do
 			if [[ ! -f ${file} ]]; then
 				echo "not a file: ${file}" 1>&2
 				continue
 			fi
+
+			# build a list of file names that are going to be uploaded (needed for file upload initialization)
+			# note: this list is going to start with a comma (','), which has to be considered when using it
 			file_name=$(basename ${file})
 			files+=( ${file_name} )
 			file_object="{\"key\":\"${file_name}\"}"
@@ -116,30 +134,37 @@ for record in ${record_dirs[@]}; do
 		done
 	fi
 
+	# initialize the record's files (send the list of files that are expected to be uploaded)
 	curl -sk -X POST -H "${json_header}" -H "${auth_header}" -d "[${file_objects:1}]" ${base_url}/api/records/${recid}/draft/files > /dev/null
 
+	# upload each file's content, and finalize (commit) the upload
 	for file in ${files[@]}; do
 		file_base_url=${base_url}/api/records/${recid}/draft/files/${file}
 		curl -sk -X PUT -H "${octet_header}" -H "${auth_header}" --upload-file ${record}/files/${file} ${file_base_url}/content > /dev/null
 		curl -sk -X POST -H "${auth_header}" ${file_base_url}/commit > /dev/null
 	done
 
+	# if not specifically requested otherwise, publish the newly created draft
 	if [[ $publish -gt 0 ]]; then
 		curl -sk -X POST -H "${auth_header}" ${base_url}/api/records/${recid}/draft/actions/publish > /dev/null
 	fi
 done
 
+# upload the collected metadata-only records
 for record in ${record_files[@]}; do
+	# create a new draft, with the specified metadata
 	recid=$(curl -sk -X POST -H "${json_header}" -H "${auth_header}" -d @${record} ${base_url}/api/records | jq ".id")
 	recid=${recid%\"}
 	recid=${recid#\"}
 	recids+=( ${recid} )
 
+	# if not specifically requested otherwise, publish the newly created draft
 	if [[ $publish -gt 0 ]]; then
 		curl -sk -X POST -H "${auth_header}" ${base_url}/api/records/${recid}/draft/actions/publish > /dev/null
 	fi
 done
 
+# print the recid of each created record
 for recid in ${recids[@]}; do
 	echo ${recid}
 done