# HG changeset patch
# User Franz Glasner <fzglas.hg@dom66.de>
# Date 1568014993 -7200
# Node ID c9fb9e920a32a366fb2345537b617faab9088ce4
# Parent  c95726f83f84d4058962efa079f31e53605bfde0
Docu: documented many functions

diff -r c95726f83f84 -r c9fb9e920a32 bin/check-ports
--- a/bin/check-ports	Sat Sep 07 11:48:29 2019 +0200
+++ b/bin/check-ports	Mon Sep 09 09:43:13 2019 +0200
@@ -60,6 +60,21 @@
 
 
 get_remote_repo_versions() {
+    : 'Determine the remote repository versions of all packages in
+    repository `_repo`.
+
+    Args:
+        _repo: the name of the repote repository
+
+    Returns:
+        status 0 on success, 1 on errors
+
+    Output (Globals):
+        remote_versions_${_repo}: the versions of all packages in `_repo` and
+                                  their extended version status with respect to
+                                  locally installed packages
+
+    '
     local _repo _data _rv
 
     _repo=$1
@@ -71,6 +86,26 @@
 }
 
 get_remote_repo_data() {
+    : 'Get the extended package version information from the remote repository
+    `_repo` for package `_name`.
+
+    Args:
+        _repo: the name of the remote repository
+        _name: the package name
+
+    Input (Globals):
+        remote_versions_${_repo}: the extended version info for *all* packages
+                                  in repo `_repo`.
+
+    Returns:
+        status 0 on success, 1 on errors or if the package is not found
+        in the remote repository
+
+    Output (Globals):
+        remote_label_${_repo}:
+        remote_descr_${_repo}:
+
+    '
     local _repo _name _rversions _rfqp _rl _rdescr
 
     _repo=$1
@@ -92,10 +127,34 @@
 }
 
 get_local_index_versions() {
+    : 'Determine the extendes versions of all packages in the local index
+    (ports).
+
+    Returns:
+        status 0 on success or 1 on errors
+
+    Output (Globals):
+        local_index_versions:
+
+    '
     local_index_versions=$(pkg version -I -v)
 }
 
 get_repo_for_installed_package() {
+    : 'Determine for a package `_name` from which repository is has been
+    installed.
+
+    Args:
+        _name: the name of the package to search for
+
+    Returns:
+        0 on success, 1 on errors or if the package is not installed
+
+    Output (Globals):
+        repository: the repository from which the installed packages `_name`
+                    has been installed
+
+    '
     local _name _n _v _r
 
     _name=$1
@@ -112,6 +171,24 @@
 }
 
 get_immediate_index_version() {
+    : 'Determine for package `_package` the version of the package in the
+    local ports index.
+
+    Args:
+        _package: the package name to search for
+
+    Input (Globals):
+        INDEXDIR:  the directory where to search the index file
+        INDEXFILE: the name of the index file
+
+    Returns:
+        0 on success, 1 on errors or if the package is not in the index
+
+    Output(Globals):
+        immediate_index_version: the version number of `_package` in the
+                                 index
+
+    '
     local _package _line _fqpn _n _lines
 
     _package=$1
@@ -197,6 +274,24 @@
 }
 
 print_title() {
+    : 'Print the output title line for a package
+
+    Args:
+        _package: the package name
+        _repo:    the repository name
+
+    Input (Globals).
+        title_printed: a global that determines if the title really needs
+                       to be printed.
+
+                       If it is an empty string the the title is
+                       really printed and the variable is set to
+                       "yes".
+
+    Output (Globals):
+        title_printed: set to "yes" if the title has been printed
+
+    '
     local _package _repo
 
     _package=$1