make library comments consistent and clean up code

vendor/lib/lib_base.cmd

@@ -10,26 +10,24 @@ if "%~1" == "/h" (
 
 exit /b
 
-:help
 :::===============================================================================
-:::show_subs - shows all sub routines in a .bat/.cmd file with documentation
+:::help - shows all sub routines in a .bat/.cmd file with documentation
 :::.
 :::include:
 :::.
 :::       call "lib_base.cmd"
 :::.
 :::usage:
 :::.
-:::       %lib_base% show_subs "file"
+:::       %lib_base% help "file"
 :::.
 :::options:
 :::.
 :::       file <in> full path to file containing lib_routines to display
-:::.
 :::-------------------------------------------------------------------------------
-    for /f "tokens=* delims=:" %%a in ('type "%~1" ^| %WINDIR%\System32\findstr /i /r "^:::"') do (
-        rem echo a="%%a"
 
+:help
+    for /f "tokens=* delims=:" %%a in ('%WINDIR%\System32\findstr /i /r "^:::" "%~1"') do (
         if "%%a"=="." (
             echo.
         ) else if /i "%%a" == "usage" (
@@ -44,9 +42,13 @@ exit /b
     pause
     exit /b
 
-:cmder_shell
 :::===============================================================================
-:::show_subs - shows all sub routines in a .bat/.cmd file with documentation
+:::cmder_shell - Initializes the Cmder shell environment variables
+:::.
+:::description:
+:::.
+:::       This routine sets up the Cmder shell environment by detecting the
+:::       command shell and initializing related variables.
 :::.
 :::include:
 :::.
@@ -55,14 +57,29 @@ exit /b
 :::usage:
 :::.
 :::       %lib_base% cmder_shell
+:::-------------------------------------------------------------------------------
+
+:cmder_shell
+    call :detect_comspec %ComSpec%
+    exit /b
+
+:::===============================================================================
+:::detect_comspec - Detects the command shell being used:::
 :::.
-:::options:
+:::description:
 :::.
-:::       file <in> full path to file containing lib_routines to display
+:::       This function sets the CMDER_SHELL variable to the name of the
+:::       detected command shell. It also initializes the CMDER_CLINK and
+:::       CMDER_ALIASES variables if they are not already defined.
+:::.
+:::include:
 :::.
+:::       call "lib_base.cmd"
+:::.
+:::usage:
+:::.
+:::       %lib_base% detect_comspec %ComSpec%
 :::-------------------------------------------------------------------------------
-    call :detect_comspec %ComSpec%
-    exit /b
 
 :detect_comspec
     set CMDER_SHELL=%~n1
@@ -74,6 +91,27 @@ exit /b
     )
     exit /b
 
+:::===============================================================================
+:::update_legacy_aliases - Updates the legacy alias definitions in the user_aliases file
+:::.
+:::description:
+:::.
+:::       This function checks if the user_aliases file contains the marker
+:::       ";= Add aliases below here". If the marker is not found, it creates
+:::       an initial user_aliases store by copying the default user_aliases file
+:::       from the CMDER_ROOT directory. If the CMDER_USER_CONFIG environment
+:::       variable is defined, it creates a backup of the existing user_aliases
+:::       file before copying the default file.
+:::.
+:::include:
+:::.
+:::       call "lib_base.cmd"
+:::.
+:::usage:
+:::.
+:::       %lib_base% update_legacy_aliases
+:::-------------------------------------------------------------------------------
+
 :update_legacy_aliases
     type "%user_aliases%" | %WINDIR%\System32\findstr /i ";= Add aliases below here" >nul
     if "%errorlevel%" == "1" (

vendor/lib/lib_git.cmd

@@ -12,7 +12,6 @@ if "%~1" == "/h" (
 
 exit /b
 
-:read_version
 :::===============================================================================
 :::read_version - Get the git.exe version
 :::.
@@ -34,6 +33,7 @@ exit /b
 :::  GIT_VERSION_[GIT SCOPE] <out> Env variable containing Git semantic version string
 :::-------------------------------------------------------------------------------
 
+:read_version
     :: clear the variables
     set GIT_VERSION_%~1=
 
@@ -64,7 +64,6 @@ exit /b
 
     exit /b
 
-:parse_version
 :::===============================================================================
 :::parse_version - Parse semantic version string 'x.x.x.x' and return the pieces
 :::.
@@ -89,6 +88,7 @@ exit /b
 :::  [SCOPE]_BUILD <out> Scoped Build version.
 :::-------------------------------------------------------------------------------
 
+:parse_version
     :: process a `x.x.x.xxxx.x` formatted string
     %print_debug% :parse_version "ARGV[1]=%~1, ARGV[2]=%~2"
 
@@ -111,9 +111,8 @@ exit /b
 
 :endlocal_set_git_version
 
-:validate_version
 :::===============================================================================
-:::validate_version - Validate semantic version string 'x.x.x.x'.
+:::validate_version - Validate semantic version string 'x.x.x.x'
 :::.
 :::include:
 :::.
@@ -129,6 +128,7 @@ exit /b
 :::  [VERSION]   <in> Semantic version String. Ex: 1.2.3.4
 :::-------------------------------------------------------------------------------
 
+:validate_version
     :: now parse the version information into the corresponding variables
     %print_debug% :validate_version "ARGV[1]=%~1, ARGV[2]=%~2"
 
@@ -143,9 +143,8 @@ exit /b
     )
     exit /b
 
-:compare_versions
 :::===============================================================================
-:::compare_version - Compare semantic versions return latest version.
+:::compare_version - Compare semantic versions and return latest version
 :::.
 :::include:
 :::.
@@ -161,6 +160,7 @@ exit /b
 :::  [SCOPE2]    <in> Example: VENDOR
 :::-------------------------------------------------------------------------------
 
+:compare_versions
     :: checks all major, minor, patch and build variables for the given arguments.
     :: whichever binary that has the most recent version will be used based on the return code.
 
@@ -185,7 +185,7 @@ exit /b
     endlocal & exit /b 0
 
 :::===============================================================================
-:::is_git_shim
+:::is_git_shim - Check if the directory has a git.shim file
 :::.
 :::include:
 :::.
@@ -219,7 +219,7 @@ exit /b
     exit /b
 
 :::===============================================================================
-:::compare_git_versions
+:::compare_git_versions - Compare the user git version against the vendored version
 :::.
 :::include:
 :::.
@@ -262,7 +262,7 @@ exit /b
     exit /b
 
 :::===============================================================================
-:::get_user_git_version - get the version information for the user provided git binary
+:::get_user_git_version - Get the version information for the user provided git binary
 :::.
 :::include:
 :::.
@@ -278,5 +278,4 @@ exit /b
     %lib_git% read_version USER "%test_dir%" 2>nul
     %print_debug% ":get_user_git_version" "get_user_git_version GIT_VERSION_USER: %GIT_VERSION_USER%"
     %lib_git% validate_version USER %GIT_VERSION_USER%
-    exit  /b
-
+    exit /b

vendor/lib/lib_profile.cmd

@@ -12,26 +12,26 @@ if "%~1" == "/h" (
 
 exit /b
 
-:run_profile_d
 :::===============================================================================
-:::run_profile_d - Run all scripts in the passed dir path
-:::
+:::run_profile_d - Run all scripts in the passed directory path
+:::.
 :::include:
-:::
+:::.
 :::  call "lib_profile.cmd"
-:::
+:::.
 :::usage:
-:::
+:::.
 :::  %lib_profile% "[dir_path]"
-:::
+:::.
 :::required:
-:::
+:::.
 :::  [dir_path] <in> Fully qualified directory path containing init *.cmd|*.bat.
 :::                  Example: "c:\bin"
-:::
+:::.
 :::  path       <out> Sets the path env variable if required.
 :::-------------------------------------------------------------------------------
 
+:run_profile_d
     if not exist "%~1" (
         mkdir "%~1"
     )
@@ -43,4 +43,3 @@ exit /b
     )
     popd
     exit /b
-