Some comments added and embedded --playlist in --list

src/main.sh

@@ -2,6 +2,31 @@
 
 set -eu
 
+# The user interface of this application is composed out of the following
+# views.
+# - VIEW_ARTIST: Show all release group of an artist
+# - VIEW_RELEASEGROUP: Show all releases within a release group
+# - VIEW_RELEASE: Show track list of release
+# - VIEW_SEARCH_ARTIST: Interface to search artists on MusicBrainz
+# - VIEW_SEARCH_ALBUM: Interface to search albums (release groups) on MusicBrainz
+# - VIEW_LIST_ARTISTS: Presentation of all artists in the local database
+# - VIEW_LIST_ALBUMS: Presentation of all albums (release groups) in the local database
+# - VIEW_SELECT_ARTIST: Interface for the user to select an artist
+# - VIEW_PLAYLIST: View on the currently loaded playlist and playlist manipulation
+# - VIEW_QUIT: Exiting view, to terminate the application
+#
+# All views but the last three are handled within a single fzf instance. The
+# views VIEW_SELECT_ARTIST, and VIEW_PLAYLIST run each in a separate fzf
+# instance. The last view (VIEW_QUIT) does nothing but terminate the
+# application.
+#
+# The fzf instance comprising VIEW_ARTIST - VIEW_LIST_ALBUMS is always in one
+# of two modes: normale mode (MODE_NORMAL) or insert mode (MODE_INSERT). Both
+# modes come with different key bindings. It is only in the insert mode that
+# the query string can be written.
+#
+# All views and modes are referred to by the following constants. The values
+# are arbitrary but distinct.
 VIEW_ARTIST="artist"
 VIEW_RELEASEGROUP="rg"
 VIEW_RELEASE="release"
@@ -72,30 +97,42 @@ MODE_INSERT="show"
 # FZF handlers
 . "sh/fzf.sh"
 
+# Command-line options that may only be used internally.
 case "${1:-}" in
 "--lines")
+  # Print lines that are fed into fzf.
+  #
+  # @argument $2: view
+  # @argument $3: MusicBrainz ID
+  #
+  # The first argument `view` may be one of VIEW_ARTIST, VIEW_RELEASEGROUP,
+  # VIEW_RELEASE, VIEW_LIST_ARTISTS, VIEW_LIST_ALBUMS, and VIEW_PLAYLIST. The
+  # MusicBrainz ID  is required for the first three views, and denotes the
+  # MusicBrainz ID of the respective object.
   view=${2:-}
   mbid=${3:-}
   case "$view" in
-  "$VIEW_ARTIST")
+  "$VIEW_ARTIST") list_releasegroups "$mbid" ;;
-    list_releasegroups "$mbid"
+  "$VIEW_RELEASEGROUP") list_releases "$mbid" ;;
-    ;;
+  "$VIEW_RELEASE") list_recordings "$mbid" ;;
-  "$VIEW_RELEASEGROUP")
+  "$VIEW_LIST_ARTISTS") list_local_artists ;;
-    list_releases "$mbid"
+  "$VIEW_LIST_ALBUMS") list_local_releasegroups ;;
-    ;;
+  "$VIEW_PLAYLIST") list_playlist ;;
-  "$VIEW_RELEASE")
-    list_recordings "$mbid"
-    ;;
-  "$VIEW_LIST_ARTISTS")
-    list_local_artists
-    ;;
-  "$VIEW_LIST_ALBUMS")
-    list_local_releasegroups
-    ;;
   esac
   exit 0
   ;;
 "--playback")
+  # Control mpv instance
+  #
+  # @argument $2: view
+  # @argument $3: MusicBrainz ID of current object
+  # @argument $4: MusicBrainz ID of selected object
+  # @argument $5: Path to decoration file
+  #
+  # This option controls the mpv instance via a key pressed in fzf. The key
+  # pressed is stored in the environment variable FZF_KEY and is resolved to
+  # the playback command through the method `playback_cmd_from_key` (see
+  # `src/sh/playback.sh` for a description of all playback commands).
   view=${2:-}
   mbid_current="${3:-}"
   mbid="${4:-}"
@@ -138,6 +175,14 @@ case "${1:-}" in
   exit 0
   ;;
 "--filter")
+  # fzf instructions to invoke filters
+  #
+  # @argument #2: mode
+  # @argument #3: view
+  #
+  # This option takes the key pressed (FZF_KEY), translates it to the preset
+  # query of that key in that view, and prints the fzf instructions which sets
+  # that query.
   mode=$2
   view=$3
   q="$(default_query "$view" "$FZF_KEY")"
@@ -147,6 +192,21 @@ case "${1:-}" in
   exit 0
   ;;
 "--jumpto-artist")
+  # fzf instructions to go to artist
+  #
+  # @argument $2: mode
+  # @argument $3: view
+  # @argument $4: MusicBrainz ID of current object
+  # @argument $5: MusicBrainz ID of selected object
+  #
+  # With this option, fzf instructions are printed that divert the user to the
+  # view VIEW_ARTIST of the artist of the selected object (of it is a
+  # single-artist object), or that divert the user to a choice
+  # (VIEW_SELECT_ARTIST) of all artists of the selected object. In the view
+  # VIEW_PLAYLIST, the latter path is also taken for single-artist objects. The
+  # reason for this is that VIEW_PLAYLIST and VIEW_ARTIST are not implemented
+  # in the same fzf instance, and VIEW_SELECT_ARTIST already provides an
+  # interface to switch from VIEW_PLAYLIST to VIEW_ARTIST.
   mode=$2
   view=$3
   mbid_cur="${4:-}"
@@ -206,8 +266,6 @@ case "${1:-}" in
   # - VIEW_RELEASEGROUP: For single-artist release groups, divert to
   #   VIEW_ARTIST of that artist, else display the artist selection.
   # - VIEW_RELEASE: Divert view to VIEW_LIST_RELEASEGROUP.
-  #
-  # Hence, the view is only diverted in this last case.
   mode="${2:-"$MODE_NORMAL"}"
   view="${3:-"$VIEW_LIST_ARTISTS"}"
   mbid="${4:-}"
@@ -335,10 +393,6 @@ case "${1:-}" in
   printf "pos(%s)" $((pos + 1))
   exit 0
   ;;
-"--playlist")
-  list_playlist
-  exit 0
-  ;;
 "--help")
   cat <<EOF
 Usage: $0 [OPTION]
@@ -460,7 +514,7 @@ IN_SEARCH_ARTIST_VIEW="$(printf "$IN_VIEW_PATTERN" "$VIEW_SEARCH_ARTIST")"
 IN_SEARCH_ALBUM_VIEW="$(printf "$IN_VIEW_PATTERN" "$VIEW_SEARCH_ALBUM")"
 FZF_CURRENT_MODE="\$FZF_INPUT_STATE"
 FZF_CURRENT_VIEW="\$FZF_BORDER_LABEL"
-FZF_RELOAD_PLAYLIST="reload-sync($0 --playlist)"
+FZF_RELOAD_PLAYLIST="reload-sync($0 --lines $VIEW_PLAYLIST)"
 FZF_POS_PLAYLIST="transform:$0 --playlist-place-cursor"
 PUT_FZF_KEY_LOGIC="case \$FZF_KEY in space) echo \"put( )\";; left) echo backward-char;; right) echo forward-char;; backspace|bspace|bs) echo backward-delete-char;; delete|del) echo delete-char;; *) echo \"put(\$FZF_KEY)\";; esac"
 while true; do