commented sh files

src/sh/local.sh

@@ -1,3 +1,8 @@
+# Database functionality to support local music.
+#
+# All local data is stored in the directory `LOCALDATADIR`. In the future, we
+# will also use the methods here, and modifications thereof, to support
+# MusicBainz collections.
 if [ ! "${LOCAL_LOADED:-}" ]; then
   LOCALDATADIR="$HOME/.cache/$APP_NAME/local"
   LOCALDATA_ARTISTS="$LOCALDATADIR/artists"
@@ -19,7 +24,13 @@ if [ ! "${LOCAL_LOADED:-}" ]; then
   export LOCAL_LOADED=1
 fi
 
-gettags() {
+# Retrieve tags as json object from music file
+#
+# @argument $1: path to music file
+#
+# The tags retrieved are the MusicBrainz release ID and the MusicBrainz track
+# ID
+__gettags() {
   ffprobe -v error -show_entries format_tags -print_format json "$1" |
     $JQ '.format.tags | {
       trackid: (."MusicBrainz Release Track Id" // ."MUSICBRAINZ_RELEASETRACKID" // ."MusicBrainz/Release Track Id" // ""),
@@ -27,9 +38,14 @@ gettags() {
     }'
 }
 
-# Read music files in specified directory and create json file that points to
-# all relevant MusicBrainz IDs.
+# Decorate locally available music
+#
 # @input $1: Path to directory with album
+#
+# This methods reads the music files in the specified directory and writes a
+# json file that points to all relevant MusicBrainz IDs. If the directory
+# contains untagged files, or files of different releases, then the decoration
+# process will fail, and an error is printed.
 decorate() {
   if [ -f "$1/$DECORATION_FILENAME" ]; then
     info "Directory $1 has already been decorated (skipping)"
@@ -39,7 +55,7 @@ decorate() {
   tmpf=$(mktemp)
   (cd "$1" && find . -type f -iname '*.mp3' -o -iname '*.mp4' -o -iname '*.flac' -o -iname '*.m4a') >"$tmpf"
   while IFS= read -r f; do
-    mbid=$(gettags "$1/$f")
+    mbid=$(__gettags "$1/$f")
     rid=$(echo "$mbid" | $JQ '.releaseid')
     tid=$(echo "$mbid" | $JQ '.trackid')
     if [ ! "$rid" ] || [ ! "$tid" ]; then
@@ -105,7 +121,13 @@ __batch_load_missing() {
   rm -f "$tmpf"
 }
 
-# Precompute views
+# Precompute lists
+#
+# The main views (VIEW_ARTIST and TYPE_RELEASEGROUP) for locally available
+# music are theme dependent. These views are generated from the lists that are
+# produced with the present method. It contains all essential data, but in a
+# theme-independent fashion. The lists are stored in the files
+# `LOCALDATA_ARTISTS_LIST` and `LOCALDATA_RELEASEGROUPS_LIST`.
 __precompute_lists() {
   cache_get_file_batch "$TYPE_ARTIST" <"$LOCALDATA_ARTISTS" | xargs \
     $JQ '[
@@ -125,23 +147,13 @@ __precompute_lists() {
       .title,
       (."artist-credit" | map(([.name, .joinphrase]|join(""))) | join(""))
       ] | join("\t")' >"$LOCALDATA_RELEASEGROUPS_LIST"
-  #  cache_get_file_batch "$TYPE_RELEASE" <"$LOCALDATA_RELEASES" | xargs \
-  #    $JQ '[
-  #      .id,
-  #      .status,
-  #      .date,
-  #      ."cover-art-archive".count,
-  #      (."label-info" | map(.label.name) | unique | join(", ")),
-  #      (.media | map(."track-count") | add),
-  #      (.media | map(.format) | unique | join(", ")),
-  #      .country,
-  #      .title,
-  #      (."artist-credit" | map(([.name, .joinphrase]|join(""))) | join(""))
-  #      ] | join("\t")' >"$LOCALDATA_RELEASES_LIST" &
 }
 
 # Precompute views
-# TODO: The sed opperations take too long, improve!
+#
+# This method injects the theme elements to the lists from `precompute_lists`.
+# The resulting views are stored in the files `LOCALDATA_ARTISTS_VIEW` and
+# `LOCALDATA_RELEASEGROUPS_VIEW`.
 precompute_views() {
   awk \
     -F "\t" \
@@ -193,7 +205,9 @@ precompute_views() {
 # argument $1: path to decorated music files
 #
 # This method parses all decorations and generates a line-by-line database of
-# locally available artists, releases, and release groups.
+# locally available artists, releases, and release groups. This data is stored
+# in the files `LOCALDATA_ARTISTS`, `LOCALDATA_RELEASES`, and
+# `LOCALDATA_RELEASEGROUPS`.
 reloaddb() {
   rm -rf "$LOCALDATADIR"
   mkdir -p "$LOCALDATADIR"
@@ -225,16 +239,24 @@ reloaddb() {
 }
 
 # Check if necessary cache files are present or not
+#
+# This method returns a non-zero value if some cached file is required to exist
+# for the computation of the lists (and views). This does not include the
+# derivation of the MusicBrainz artist IDs and MusicBrainz release-group IDs
+# from the MusicBrainz releases (see the `reloaddb` method above).
 local_files_present() {
   cache_get_file_batch "$TYPE_ARTIST" <"$LOCALDATA_ARTISTS" | xargs ls >/dev/null 2>&1 || return 1
   cache_get_file_batch "$TYPE_RELEASEGROUP" <"$LOCALDATA_RELEASEGROUPS" | xargs ls >/dev/null 2>&1 || return 1
-  cut -d "$(printf '\t')" -f 1 "$LOCALDATA_RELEASES" | cache_get_file_batch "$TYPE_RELEASEGROUP" | xargs ls >/dev/null 2>&1 || return 1
+  #cut -d "$(printf '\t')" -f 1 "$LOCALDATA_RELEASES" | cache_get_file_batch "$TYPE_RELEASE" | xargs ls >/dev/null 2>&1 || return 1
   return 0
 }
 
 # Load missing files
+#
+# If missing files were detected with `local_files_present`, then these missing
+# files may be cached using the present method.
 load_missing_files() {
   __batch_load_missing "$TYPE_ARTIST" <"$LOCALDATA_ARTISTS"
   __batch_load_missing "$TYPE_RELEASEGROUP" <"$LOCALDATA_RELEASEGROUPS"
-  cut -d "$(printf '\t')" -f 1 "$LOCALDATA_RELEASES" | __batch_load_missing "$TYPE_RELEASE"
+  #cut -d "$(printf '\t')" -f 1 "$LOCALDATA_RELEASES" | __batch_load_missing "$TYPE_RELEASE"
 }