Add some comments to several functions

libpacaur/cache.sh

@@ -10,6 +10,7 @@
 # usage: CleanCache( $packages )
 ##
 CleanCache() {
+    # clean AUR sources cache
     if [[ $SRCDEST ]]; then
         [[ $count -eq 1 ]] && printf "\n%s\n %s\n" $"Sources to keep:" $"All development packages sources"
         printf "\n%s %s\n" $"AUR source cache directory:" "$SRCDEST"
@@ -25,6 +26,7 @@ CleanCache() {
             fi
         fi
     fi
+    # clean clone directory cache
     if [[ -d "$clonedir" ]]; then
         cd $clonedir
         [[ $count -eq 1 ]] && printf "\n%s\n %s\n" $"Clones to keep:" $"All packages clones"

libpacaur/checks.sh

@@ -27,13 +27,15 @@ IgnoreChecks() {
 
     checkaurpkgsAver=($(GetJson "var" "$json" "Version"))
     checkaurpkgsQver=($(expac -Q '%v' "${checkaurpkgs[@]}"))
+    # set always the latest revision for devel packages since the RPC data is static only
     for i in "${!checkaurpkgs[@]}"; do
         [[ -n "$(grep -E "\-(cvs|svn|git|hg|bzr|darcs|nightly.*)$" <<< ${checkaurpkgs[$i]})" ]] && checkaurpkgsAver[$i]=$"latest"
     done
     for i in "${!checkaurpkgs[@]}"; do
         unset isignored
         if [[ " ${ignoredpkgs[@]} " =~ " ${checkaurpkgs[$i]} " ]]; then
             isignored=true
+        # check ignored groups
         elif [[ -n "${ignoredgrps[@]}" ]]; then
             unset checkaurpkgsAgrp checkaurpkgsQgrp
             checkaurpkgsAgrp=($(GetJson "arrayvar" "$json" "Groups" "${checkaurpkgs[$i]}"))
@@ -48,6 +50,7 @@ IgnoreChecks() {
 
         if [[ $isignored = true ]]; then
             if [[ ! $upgrade ]]; then
+                # ask for installing ignored package
                 if [[ ! $noconfirm ]]; then
                     if ! Proceed "y" $"${checkaurpkgs[$i]} is in IgnorePkg/IgnoreGroup. Install anyway?"; then
                         Note "w" $"skipping target: ${colorW}${checkaurpkgs[$i]}${reset}"
@@ -85,11 +88,12 @@ IgnoreDepsChecks() {
     # add checked targets
     deps=(${aurpkgs[@]})
 
-    # check dependencies
+    # check repo dependencies
     for i in "${repodepspkgs[@]}"; do
         unset isignored
         if [[ " ${ignoredpkgs[@]} " =~ " $i " ]]; then
             isignored=true
+        # check ignored groups
         elif [[ -n "${ignoredgrps[@]}" ]]; then
             unset repodepspkgsSgrp repodepspkgsQgrp
             repodepspkgsSgrp=($(expac -S -1 '%G' "$i"))
@@ -102,6 +106,7 @@ IgnoreDepsChecks() {
             done
         fi
 
+        # check unresolved ignored dependencies
         if [[ $isignored = true ]]; then
             if [[ ! $upgrade ]]; then
                 Note "w" $"skipping target: ${colorW}$i${reset}"
@@ -111,6 +116,7 @@ IgnoreDepsChecks() {
             Note "e" $"Unresolved dependency '${colorW}$i${reset}'"
         fi
     done
+    # check aur dependencies
     for i in "${aurdepspkgs[@]}"; do
         # skip already checked dependencies
         [[ " ${aurpkgs[@]} " =~ " $i " ]] && continue
@@ -119,6 +125,7 @@ IgnoreDepsChecks() {
         unset isignored
         if [[ " ${ignoredpkgs[@]} " =~ " $i " ]]; then
             isignored=true
+        # check ignored groups
         elif [[ -n "${ignoredgrps[@]}" ]]; then
             unset aurdepspkgsAgrp aurdepspkgsQgrp
             aurdepspkgsAgrp=($(GetJson "arrayvar" "$json" "Groups" "$i"))
@@ -131,7 +138,9 @@ IgnoreDepsChecks() {
             done
         fi
 
+        # check unresolved ignored dependencies
         if [[ $isignored = true ]]; then
+            # ask for installing ignored dependencies
             if [[ ! $noconfirm ]]; then
                 if ! Proceed "y" $"$i dependency is in IgnorePkg/IgnoreGroup. Install anyway?"; then
                     Note "w" $"skipping target: ${colorW}$i${reset}"
@@ -184,6 +193,7 @@ ProviderChecks() {
             [[ " ${provided[@]} " =~ " ${providersdeps[$i]} " ]] && continue
         fi
 
+        # select providers, select default provider=0 if noconfirm option is set
         if [[ ! $noconfirm ]]; then
             Note "i" $"${colorW}There are ${#providers[@]} providers available for ${providersdeps[$i]}:${reset}"
             expac -S -1 '   %!) %n (%r) ' "${providers[@]}"
@@ -231,7 +241,7 @@ ProviderChecks() {
 
     FindDepsRepoProvider ${providerspkgs[@]}
 
-    # get binary packages info
+    # get repo packages info
     if [[ -n "${repodepspkgs[@]}" ]]; then
         repodepspkgs=($(expac -S -1 '%n' "${repodepspkgs[@]}" | LC_COLLATE=C sort -u))
         repodepsSver=($(expac -S -1 '%v' "${repodepspkgs[@]}"))
@@ -393,9 +403,11 @@ ReinstallChecks() {
     # global aurpkgs aurdepspkgs deps aurconflictingpkgs depsAname depsQver depsAver depsAood depsAmain
     depsAtmp=(${depsAname[@]})
     for i in "${!depsAtmp[@]}"; do
+        # check and skip packages with conflicts to avoid false positive
         [[ ! $foreign ]] && [[ ! " ${aurpkgs[@]} " =~ " ${depsAname[$i]} " || " ${aurconflictingpkgs[@]} " =~ " ${depsAname[$i]} " ]] && continue
         [[ -z "${depsQver[$i]}" || "${depsQver[$i]}" = '#' || $(vercmp "${depsAver[$i]}" "${depsQver[$i]}") -gt 0 ]] && continue
         [[ ! $installpkg && ! " ${aurdepspkgs[@]} " =~ " ${depsAname[$i]} " ]] && continue
+        # devel packages are not considered, VCS packages version is not checked by design since it is a slow operation
         if [[ -n "$(grep -E "\-(cvs|svn|git|hg|bzr|darcs|nightly.*)$" <<< ${depsAname[$i]})" ]]; then
             Note "w" $"${colorW}${depsAname[$i]}${reset} latest revision -- fetching"
         else

libpacaur/deps.sh

@@ -100,7 +100,7 @@ DepsSolver() {
         exit 1
     fi
 
-    # return all binary deps
+    # return all repo deps
     FindDepsRepo ${repodeps[@]}
 
     # avoid possible duplicate
@@ -216,13 +216,13 @@ FindDepsAur() {
             depspkgstmp+=($(grep -xvf <(printf '%s\n' "${vcsdepspkgs[@]}") <(printf '%s\n' "${depspkgs[@]}")))
             depspkgs=($(tr ' ' '\n' <<< ${depspkgstmp[@]} | LC_COLLATE=C sort -u))
         fi
-        # remove installed binary packages only
+        # remove installed repo packages only
         if [[ $foreign ]]; then
             depspkgs=($(grep -xf <(printf '%s\n' "${depspkgs[@]}") <(printf '%s\n' "${foreignpkgs[@]}")))
         fi
     fi
 
-    # split binary and AUR depends pkgs
+    # split repo and AUR depends pkgs
     unset depspkgsaur
     if [[ -n "${depspkgs[@]}" ]]; then
         # remove all pkgs versioning
@@ -390,14 +390,14 @@ FindDepsRepo() {
     # global repodeps repodepspkgs
     [[ -z "${repodeps[@]}" ]] && return
 
-    # reduce root binary deps
+    # reduce root repo deps
     repodeps=($(tr ' ' '\n' <<< ${repodeps[@]} | sort -u))
 
     # add initial repodeps
     [[ -z "${repodepspkgs[@]}" ]] && repodepspkgs=(${repodeps[@]})
 
     # get non installed repo deps
-    allrepodepspkgs=($(expac -S -1 '%E' ${repodeps[@]})) # no version check needed as all deps are binary
+    allrepodepspkgs=($(expac -S -1 '%E' ${repodeps[@]})) # no version check needed as all deps are repo deps
     [[ -n "${allrepodepspkgs[@]}" ]] && repodepspkgstmp=($($pacmanbin -T ${allrepodepspkgs[@]} | sort -u))
 
     if [[ -n "${repodepspkgstmp[@]}" ]]; then
@@ -418,14 +418,14 @@ FindDepsRepoProvider() {
     # global repodeps repodepspkgs
     [[ -z "${providerspkgs[@]}" ]] && return
 
-    # reduce root binary deps
+    # reduce root repo deps
     providerspkgs=($(tr ' ' '\n' <<< ${providerspkgs[@]} | sort -u))
 
     # add initial repodeps
     [[ -z "${providerspkgspkgs[@]}" ]] && providerspkgspkgs=(${providerspkgs[@]})
 
     # get non installed repo deps
-    allproviderrepodepspkgs=($(expac -S -1 '%E' ${providerspkgs[@]})) # no version check needed as all deps are binary
+    allproviderrepodepspkgs=($(expac -S -1 '%E' ${providerspkgs[@]})) # no version check needed as all deps are repo deps
     [[ -n "${allproviderrepodepspkgs[@]}" ]] && providerrepodepspkgstmp=($($pacmanbin -T ${allproviderrepodepspkgs[@]} | sort -u))
 
     if [[ -n "${providerrepodepspkgstmp[@]}" ]]; then

libpacaur/main.sh

@@ -35,6 +35,7 @@ Prompt() {
     local i binaryksize sumk summ builtpkg cachedpkgs strname stroldver strnewver strsize action
     local depsver repodepspkgsver strrepodlsize strrepoinsize strsumk strsumm lreposizelabel lreposize
     # global repodepspkgs repodepsSver depsAname depsAver depsArepo depsAcached lname lver lsize deps depsQver repodepspkgs repodepsSrepo repodepsQver repodepsSver
+
     # compute binary size
     if [[ -n "${repodepspkgs[@]}" ]]; then
         binaryksize=($(expac -S -1 '%k' "${repodepspkgs[@]}"))
@@ -59,6 +60,7 @@ Prompt() {
         unset builtpkg
     done
 
+    # use output verbosity options from pacman config file
     if [[ -n "$(grep '^VerbosePkgLists' '/etc/pacman.conf')" ]]; then
         straurname=$"AUR Packages  (${#deps[@]})"; strreponame=$"Repo Packages (${#repodepspkgs[@]})"; stroldver=$"Old Version"; strnewver=$"New Version"; strsize=$"Download Size"
         depsArepo=(${depsAname[@]/#/aur/})
@@ -76,6 +78,7 @@ Prompt() {
             printf "%-${lname}s  ${colorR}%-${lver}s${reset}  ${colorG}%-${lver}s${reset}  %${lsize}s\n" "${depsArepo[$i]}" "${depsQver[$i]}" "${depsAver[$i]}" "${depsAcached[$i]}";
         done
 
+        # format and print binary size
         if [[ -n "${repodepspkgs[@]}" ]]; then
             for i in "${!repodepspkgs[@]}"; do
                 binarysize[$i]=$(awk '{ printf("%.2f\n", $1/$2) }' <<< "${binaryksize[$i]} 1048576")
@@ -97,6 +100,7 @@ Prompt() {
         [[ -n "${repodepspkgs[@]}" ]] && printf "${colorW}%-16s${reset} %s\n" $"Repo Packages (${#repodepspkgs[@]})" "$repodepspkgsver"
     fi
 
+    # show total download and installed size of the operation
     if [[ -n "${repodepspkgs[@]}" ]]; then
         strrepodlsize=$"Repo Download Size:"; strrepoinsize=$"Repo Installed Size:"; strsumk=$"$sumk MiB"; strsumm=$"$summ MiB"
         lreposizelabel=$(GetLength "$strrepodlsize" "$strrepoinsize")

libpacaur/pkgs.sh

@@ -75,6 +75,7 @@ EditPkgs() {
         cd "$clonedir/$i" || exit 1
         unset timestamp
         GetInstallScripts $i
+        # ask for showing files and diff when edit argument is not used
         if [[ ! $edit ]]; then
             if [[ ! $displaybuildfiles = none ]]; then
                 if [[ $displaybuildfiles = diff && -e ".git/HEAD.prev" ]]; then
@@ -136,6 +137,7 @@ EditPkgs() {
         fi
     done
 
+    # handle errors on viewing package install script and pkgbuild
     if [[ -n "${erreditpkg[@]}" ]]; then
         for i in "${erreditpkg[@]}"; do
             Note "f" $"${colorW}$i${reset} errored on exit"
@@ -212,6 +214,7 @@ MakePkgs() {
             fi
         done
 
+        # verify source integrity
         if [[ ! $builtpkg || $rebuild ]]; then
             cd "$clonedir/${basepkgs[$i]}" || exit 1
             Note "i" $"Checking ${colorW}${pkgsdeps[$i]}${reset} integrity..."
@@ -225,6 +228,8 @@ MakePkgs() {
             makepkg -odC --skipinteg ${makeopts[@]} &>/dev/null
         fi
     done
+
+    # handle errors on integrity check
     if [[ -n "${errmakepkg[@]}" ]]; then
         for i in "${errmakepkg[@]}"; do
             Note "f" $"failed to verify ${colorW}$i${reset} integrity"
@@ -300,7 +305,7 @@ MakePkgs() {
         # build
         Note "i" $"Building ${colorW}${pkgsdeps[$i]}${reset} package(s)..."
 
-        # install then remove binary deps
+        # install then remove repo dependencies
         makeopts=(${makeopts[@]/-r/})
 
         if [[ ! $installpkg ]]; then
@@ -367,7 +372,7 @@ MakePkgs() {
             Note "i" $"Removing installed AUR dependencies..."
             sudo $pacmanbin -Rsn ${aurdepspkgs[@]} --noconfirm
         fi
-        # readd removed conflicting packages
+        # readd previously removed conflicting packages
         [[ -n "${aurconflictingpkgsrm[@]}" ]] && sudo $pacmanbin -S ${aurconflictingpkgsrm[@]} --ask 36 --asdeps --needed --noconfirm
         [[ -n "${repoconflictingpkgsrm[@]}" ]] && sudo $pacmanbin -S ${repoconflictingpkgsrm[@]} --ask 36 --asdeps --needed --noconfirm
     fi

libpacaur/utils.sh

@@ -16,7 +16,7 @@ Proceed() {
         y)  printf "${colorB}%s${reset} ${colorW}%s${reset}" "::" "$2 [$Y/$n] "
             if [[ ! $noconfirm ]]; then
                 case "$TERM" in
-                    dumb)
+                    dumb) # handle line buffering on dumb terminals
                         read -r answer
                         ;;
                     *)
@@ -39,7 +39,7 @@ Proceed() {
         n)  printf "${colorB}%s${reset} ${colorW}%s${reset}" "::" "$2 [$y/$N] "
             if [[ ! $noconfirm ]]; then
                 case "$TERM" in
-                    dumb)
+                    dumb) # handle line buffering on dumb terminals
                         read -r answer
                         ;;
                     *)