# HG changeset patch
# User Matti Hamalainen <ccr@tnsp.org>
# Date 1613473610 -7200
# Node ID 77c9feb5dceef3df6fe3474ddb43e58e0e4fecdc
# Parent  1b743b80524b5287ab1ba739a0b7d72588062cd1
tj: Add numerous comments.

diff -r 1b743b80524b -r 77c9feb5dcee tj.tcl
--- a/tj.tcl	Tue Feb 16 13:01:29 2021 +0200
+++ b/tj.tcl	Tue Feb 16 13:06:50 2021 +0200
@@ -247,6 +247,7 @@
       set uid [tj_get_default_id $uhand]
     }
 
+    # Do we have any arguments left?
     if {![utl_arg_get $rarglist rindex rarg 1]} {
       tj_msg $upublic $unick $uchan "help_set"
       return 1
@@ -276,6 +277,7 @@
       # Check for days
       if {$dsign == "-"} { set rdays [expr -$rdays] }
 
+      # Check for hours
       set rhours 0
       if {[utl_arg_get $rarglist rindex rarg 0]} {
         if {[regexp {(\+|\-)?(\d+)} $rarg -> hsign rhours]} {
@@ -283,8 +285,10 @@
           incr rindex
         }
 
+        # Get description, if any
         tj_arg_rest $rarglist $rindex rdesc
 
+        # Validate hours parameters a bit
         if {$rhours < -24 || $rhours > 24} {
           tj_msg $upublic $unick $uchan "err_invalid_hours" [list $rhours]
           return 1
@@ -294,7 +298,7 @@
       # Compute target timestamp
       set rstamp [expr $uclock + ($rdays * 24 * 60 * 60) + ($rhours * 60 * 60)]
     } else {
-      # Only description, if any
+      # Only description was specified
       incr rindex -1
       tj_arg_rest $rarglist $rindex rdesc
       set rstamp "invalid"
@@ -308,14 +312,18 @@
       set umode 0
       set cid $id
       set ctarget $utarget
+
+      # If description has not been set, fetch previous
       if {$rdesc == "*"} {
         set rdesc $udesc
       }
       incr nres
     }
 
-    # Check for DB sanity
+    # Check for DB sanity at this point
     if {$nres > 1} {
+      # If we have more than one result for this ID, there's been
+      # some kind of mistake at some point.
       tj_msg $upublic $unick $uchan "err_db_corrupt" [list $nres]
       tj_log "too many $nres fatal error piip"
       return 1
@@ -323,18 +331,22 @@
 
     # Check if we are trying to add a new entry without valid timestamp
     if {$rstamp == "invalid"} {
+      # Yes, if mode is "new", we should error out
       if {$umode} {
         tj_msg $upublic $unick $uchan "err_missing_timestamp"
         return 1
       }
 
+      # Otherwise we are updating, so just use the old timestamp
       set rdate $ctarget
       set ustamp [utl_sql_datetime_to_stamp $ctarget]
     } else {
+      # Timestamp was okay
       set rdate [utl_sql_stamp_to_datetime $rstamp]
       set ustamp $rstamp
     }
 
+    # If description has not been set, use default
     if {$rdesc == "*"} {
       set rdesc $tj_default_desc
     }
@@ -342,7 +354,7 @@
     set utjstr [tj_get_tj_str_delta $ustamp $uclock]
     set udate [tj_ctime $ustamp]
 
-    # Max reminders ..
+    # Check against max reminders ..
     set usql "SELECT COUNT(*) FROM tj WHERE uuser='[utl_escape $uhand]'"
     if {[catch {set nitems [tj_dbh onecolumn $usql]} uerrmsg]} {
       tj_msg $upublic $unick $uchan "err_sql" [list $uerrmsg]
@@ -350,8 +362,8 @@
       return 1
     }
 
-    # Check for maximum reminders
     if {$nitems >= $tj_max_items} {
+      # User has too many set already
       tj_msg $upublic $unick $uchan "err_too_many" [list $nitems $tj_max_items]
       return 1
     }
@@ -389,6 +401,7 @@
         }
       }
 
+      # Do a query
       set usql "SELECT * FROM tj WHERE uuser='[utl_escape $uhand]' AND uid LIKE '[utl_escape $uid]'"
       tj_dbh eval $usql {
         set utjstr [tj_get_tj_str_delta [utl_sql_datetime_to_stamp $utarget] $uclock]
@@ -398,6 +411,7 @@
     }
 
   } elseif {[tj_cmd_match "remind" $rcmd]} {
+    # XXX TODO MAYBE .. reminder functionality .. perhaps some day.
     # !tj remind #<id> <<dd.mm.yyyy [hh:mm]>|<message>>
     # !tj remind #<id> <<dd.mm [hh:mm]>|<message>>
     if {[llength $rarglist] < 3} {
@@ -414,6 +428,7 @@
       set uname $uhand
     }
 
+    # First, get count of items
     set usql "SELECT COUNT(*) FROM tj WHERE uuser='[utl_escape $uname]'"
     if {[catch {set nitems [tj_dbh onecolumn $usql]} uerrmsg]} {
       tj_msg $upublic $unick $uchan "err_sql" [list $uerrmsg]
@@ -421,6 +436,7 @@
       return 1
     }
 
+    # Then, list items
     set nitem 0
     set usql "SELECT * FROM tj WHERE uuser='[utl_escape $uname]' ORDER BY ucreated"
     tj_dbh eval $usql {
@@ -441,6 +457,7 @@
       return 1
     }
 
+    # Check if the desired item exists
     set usql "SELECT COUNT(*) FROM tj WHERE uuser='[utl_escape $uhand]' AND uid LIKE '[utl_escape $uid]'"
     if {[catch {set nitems [tj_dbh onecolumn $usql]} uerrmsg]} {
       tj_msg $upublic $unick $uchan "err_sql" [list $uerrmsg]
@@ -449,10 +466,12 @@
     }
 
     if {$nitems == 0} {
+      # No, error out
       tj_msg $upublic $unick $uchan "err_no_such_id" [list $uid]
       return 1
     }
 
+    # Delete it
     set usql "DELETE FROM tj WHERE uuser='[utl_escape $uhand]' AND uid LIKE '[utl_escape $uid]'"
     if {[catch {set ndone [tj_dbh onecolumn $usql]} uerrmsg]} {
       tj_msg $upublic $unick $uchan "err_sql" [list $uerrmsg]