From 8db5750f4e2330652581504538d28d4bb6c80c25 Mon Sep 17 00:00:00 2001
From: tv <tv@shackspace.de>
Date: Wed, 5 Aug 2015 22:39:31 +0200
Subject: cac help harder

---
 cac | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 51 insertions(+), 8 deletions(-)

diff --git a/cac b/cac
index 985ca0e..aeda9c0 100755
--- a/cac
+++ b/cac
@@ -1,4 +1,9 @@
 #! /bin/sh
+#
+#? cac - CloudAtCost tool
+#?
+#? Usage:
+#?
 set -euf
 
 #PATH=$PWD/bin:$PATH
@@ -54,14 +59,18 @@ cac() {
   __cac_cli__"$__cac_cli__command" "$@"
 }
 
-# WIP
+#? cac help
+#?    Print this help message.
+#?
 __cac_cli__help() {(
   exec sed < "$0" -n '
-    s/^__cac_cli__\([^(]\+\)().*/\1/p
+    s/^#?\( \(.*\)\)\?/\2/p
   '
 )}
 
-# usage: console 
+#? cac console SERVERSPEC
+#?    Print console URL.
+#?
 __cac_cli__console() {(
   server=$(__cac_cli__getserver "$1")
   sid=$(echo $server | jq -r .sid)
@@ -69,10 +78,16 @@ __cac_cli__console() {(
   _cac_post_api_v1 console sid="$sid" | jq -r .console
 )}
 
+#? cac listservers
+#?    Print cached listservers JSON.
+#?
 __cac_cli__listservers() {
   jq -r . $cac_cache
 }
 
+#? cac update
+#?    Fetch and cache listservers JSON.
+#?
 __cac_cli__update() {(
   umask 0077
   servers=$(_cac_listservers)
@@ -80,6 +95,9 @@ __cac_cli__update() {(
   mv $cac_listservers_cache.tmp $cac_cache
 )}
 
+#? cac getserver SERVERSPEC
+#?    Print cached server JSON.
+#?
 __cac_cli__getserver() {(
 
   case $1 in
@@ -113,6 +131,8 @@ __cac_cli__getserver() {(
   fi
 )}
 
+#? cac generatenetworking SERVERSPEC
+#?
 __cac_cli__generatenetworking() {(
   server=$(__cac_cli__getserver "$1")
 
@@ -144,6 +164,9 @@ __cac_cli__generatenetworking() {(
   printf '}\n'
 )}
 
+#? cac powerop SERVERSPEC (poweron|poweroff|reset)
+#?    Activate server power operations.
+#?
 __cac_cli__powerop() {(
   server=$(__cac_cli__getserver "$1")
   action=$2
@@ -164,6 +187,9 @@ __cac_cli__powerop() {(
       ;;
   esac
 )}
+
+#? cac pushconfig SERVERSPEC [PREFIX=/]
+#?
 __cac_cli__pushconfig() {(
   server=$(__cac_cli__getserver "$1")
 
@@ -190,6 +216,8 @@ __cac_cli__pushconfig() {(
   ## TODO chmod and chown secrets
 )}
 
+#? cac setlabel SERVERSPEC LABEL
+#?
 __cac_cli__setlabel() {(
   server=$(__cac_cli__getserver "$1")
   label=$2
@@ -211,6 +239,8 @@ __cac_cli__setlabel() {(
   esac
 )}
 
+#? cac setmode SERVERSPEC (normal|safe)
+#?
 __cac_cli__setmode() {(
   server=$(__cac_cli__getserver "$1")
   mode=$2
@@ -232,6 +262,8 @@ __cac_cli__setmode() {(
   esac
 )}
 
+#? cac ssh SERVERSPEC
+#?
 __cac_cli__ssh() {(
   server=$(__cac_cli__getserver "$1")
   shift
@@ -251,8 +283,9 @@ __cac_cli__ssh() {(
 )}
 
 
-# usage: ./cac waitstatus mode:Safe 'Powered On'
-# blocks until server has specfied state
+#? cac waitstatus SERVERSPEC ("Powered On"|...)
+#?    Blocks until server has specfied state.
+#?
 __cac_cli__waitstatus() {
   server=$(__cac_cli__getserver "$1")
   status=$(echo $server | jq -r .status)
@@ -271,7 +304,9 @@ __cac_cli__waitstatus() {
 
 # XXX for __cac_cli__waitforcacheupdate and __cac_cli__poll cache means $cac_cache
 
-# blocks until cache has been updated then executes "$@"
+#? cac waitforcacheupdate COMMAND [ARGS...]
+#?    Blocks until cache has been updated then executes "$@".
+#?
 __cac_cli__waitforcacheupdate() {
   case $(inotifywait --format %f -q -e moved_to $(dirname $cac_cache)) in
     $(basename $cac_cache)) "$@";;
@@ -279,8 +314,9 @@ __cac_cli__waitforcacheupdate() {
   esac
 }
 
-# usage: with cac ./cac poll 60s
-# continuously update cache, sleeping at least $1 between updates
+#? cac poll [TIMESPEC=1m]
+#?    Continuously update cache, sleeping at least $1 between updates.
+#?
 __cac_cli__poll() {
   __cac_cli__update
   t=${1-1m}
@@ -290,6 +326,13 @@ __cac_cli__poll() {
 }
 
 
+#?
+#? SERVERSPEC is a query like "mode:Safe", "sdate:08/04/2015", etc.
+#? See `cac listservers` to get an inspiration.
+#?
+#? See sleep(1) for TIMESPEC.
+#?
+
 _cac_listservers() {(
   servers=$(_cac_get_api_v1 listservers)
   status=$(echo $servers | jq -r .status)
-- 
cgit v1.2.3