add comments, unify change-reload command with --lines

src/main.sh

@@ -115,6 +115,7 @@ case "${1:-}" in
   "$VIEW_LIST_ARTISTS") list_local_artists ;;
   "$VIEW_LIST_ALBUMS") list_local_releasegroups ;;
   "$VIEW_PLAYLIST") list_playlist ;;
+  "$VIEW_SEARCH_ARTIST" | "$VIEW_SEARCH_ALBUM") fzf_reload_after_change ;;
   esac
   exit 0
   ;;
@@ -319,15 +320,25 @@ case "${1:-}" in
   [ "$mode" = "$MODE_NORMAL" ] && printf "+hide-input"
   exit 0
   ;;
-"--fzf-change-reload")
-  fzf_reload_after_change
-  exit 0
-  ;;
 "--fzf-change")
+  # Trigger search on MusicBrainz
+  #
+  # @argument $2: view
+  #
+  # This stops any search being executed and initiates a new query through the
+  # MusicBrainz API. The results will be made available through the ``--lines
+  # <view>`` command.
   fzf_handle_change "$2"
   exit 0
   ;;
 "--decorate")
+  # Decorate directory with tagged audio files
+  #
+  # @argument $2: path
+  #
+  # This method reads the tags of the audio files in the specified directory.
+  # If the audio files contain MusicBrainz tags, and they are consistent, then
+  # a decoration file is written to that directory.
   [ ! "${2:-}" ] && err "You did not specify a directory." && exit 1
   [ ! -d "$2" ] && err "Path $2 does not point to a directory." && exit 1
   if ! decorate "$2"; then
@@ -337,6 +348,13 @@ case "${1:-}" in
   exit 0
   ;;
 "--reload")
+  # Reload database of local music
+  #
+  # @argument $2: path
+  #
+  # This method reconstructs the database of locally available music. This is
+  # done by traversing the directories under `path` and looking for decorated
+  # entries.
   [ ! "${2:-}" ] && err "Path to decorated music is missing." && exit 1
   [ ! -d "$2" ] && err "Path does not point to a directory." && exit 1
   info "Reloading information of local music directory $2"
@@ -345,10 +363,21 @@ case "${1:-}" in
   exit 0
   ;;
 "--preview-artist")
+  # Generate content for artist preview
+  #
+  # @argument $2: MusicBrainz Artist ID
+  #
+  # This prints the text to be displayed in the preview window for the
+  # specified artist.
   __preview_artist "$2"
   exit 0
   ;;
 "--playlistcmd")
+  # Run playback commands
+  #
+  # @argument $2: playback command (see `src/sh/playback.sh`)
+  #
+  # This is a wrapper to execute mpv commands.
   case "$2" in
   "$PLAYLIST_CMD_REMOVE") mpv_rm_index $((FZF_POS - 1)) ;;
   "$PLAYLIST_CMD_UP") mpv_playlist_move $((FZF_POS - 1)) $((FZF_POS - 2)) ;;
@@ -370,11 +399,16 @@ case "${1:-}" in
   exit 0
   ;;
 "--playlist-place-cursor")
+  # Print fzf command to replace cursor in playlist
+  #
+  # This prints the command read by a `transform` fzf binding, with which the
+  # cursor is placed on the currently played track in the playlist view.
   pos=$(mpv_playlist_position)
   printf "pos(%s)" $((pos + 1))
   exit 0
   ;;
 "--help")
+  # Print help string
   cat <<EOF
 Usage: $0 [OPTION]
 
@@ -397,6 +431,10 @@ EOF
   exit 0
   ;;
 "--refresh-view")
+  # Recompute main views
+  #
+  # With this method, the content for the views VIEW_LIST_ARTISTS and
+  # VIEW_LIST_ALBUMS are recomputed.
   precompute_view
   exit 0
   ;;
@@ -637,7 +675,7 @@ open \"\$(dirname {4})\"" \
         --bind="$KEYS_N_QUIT:transform:$IN_NORMAL_MODE && ($IN_LIST_ARTISTS_VIEW && echo \"print($VIEW_QUIT)+accept\" || $0 --draw $MODE_NORMAL $VIEW_LIST_ARTISTS) || $PUT_FZF_KEY_LOGIC" \
         --bind="$KEYS_PLAYBACK:transform:$0 --playback $FZF_CURRENT_VIEW {2} {3} {4}" \
         --bind="$KEYS_N_PLAYBACK:transform:$IN_NORMAL_MODE && $0 --playback $FZF_CURRENT_VIEW {2} {3} {4} || $PUT_FZF_KEY_LOGIC" \
-        --bind="change:execute-silent($0 --fzf-change $FZF_CURRENT_VIEW &)+reload:$0 --fzf-change-reload" \
+        --bind="change:execute-silent($0 --fzf-change $FZF_CURRENT_VIEW &)+reload:$0 --lines $FZF_CURRENT_VIEW" \
         --preview-window="right,25%,border-left,wrap,<30(hidden)" \
         --preview="$0 --preview-artist {3}" \
         --delimiter="\t" \