From 08dde00b3a25326c41f34e9eabeff44250a9cd50 Mon Sep 17 00:00:00 2001
From: Andrew Williams <andy@tensixtyone.com>
Date: Thu, 31 Jul 2025 08:26:53 +0100
Subject: [PATCH] [macos] Add docs for functions

---
 macos/.config/shell-common/macos.sh | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/macos/.config/shell-common/macos.sh b/macos/.config/shell-common/macos.sh
index 75a76bf..ab82da4 100644
--- a/macos/.config/shell-common/macos.sh
+++ b/macos/.config/shell-common/macos.sh
@@ -1,4 +1,6 @@
-# Tag the file as OK to run
+# macOS tags downloads with "com.apple.quarantine" attribute to prevent execution of downloaded files until the user explicitly allows it.
+# This function removes that attribute, allowing the file to be opened without warning.
+# Usage: itsok <file_path>
 function itsok() {
     if [[ $(uname) == "Darwin" ]]; then
         xattr -d com.apple.quarantine $1
@@ -7,12 +9,17 @@ function itsok() {
     fi
 }
 
-# Updates Homebrew installation from the Brewfile
+# Runs a brew bundle check and installs missing packages
+# Usage: update-brewfile
 function update-brewfile() {
     brew bundle check --file "$HOME/.config/Brewfile" || brew bundle --cleanup -f --file "$HOME/.config/Brewfile"
 }
 
-# Updates the dock
+# Updates the macOS Dock based on a configuration file
+# The configuration file should be in the format:
+# app_name<TAB>app_path<TAB>app_type
+# where app_type can be "persisentApps" or "other"
+# Usage: update-dock
 function update-dock() {
     idx=1
     while read entry; do