dictionary: Clean up comments a bunch

dictionary.tcl

@@ -1,11 +1,13 @@
-#
 # vim: expandtab
 #
-# bottalk script
+# This script makes the bot talk a bit. You can teach it terms to respond to. It
+# also has random responses if it sees its nick mentioned.
 #
-# this is a heavily modified version of dictionary.tcl 2.7 by perpleXa.
+# This is a heavily modified version of dictionary.tcl 2.7 by perpleXa.
+#
+# To enable the script on a channel type (partyline):
+#  .chanset #channel +dictionary
 #
-
 # Dictionary
 # Copyright (C) 2004-2007 perpleXa
 # http://perplexa.ugug.org / #perpleXa on QuakeNet
@@ -18,58 +20,52 @@
 # but WITHOUT ANY WARRANTY, to the extent permitted by law; without
 # even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 # PARTICULAR PURPOSE.
-#
-# To enable the script on a channel type (partyline):
-#  .chanset #channel +dictionary
 
 namespace eval dictionary {
-  # term/definition file.
-  # the format is a tcl dict.
+  # Definition file. The format is a tcl dict.
   variable term_file "scripts/dbase/dictionary.db"
 
-  # file containing nicks to not respond to.
-  # newline separated.
+  # File containing nicks to not respond to. Newline separated.
   variable skip_nick_file "scripts/dictionary_skip_nicks.txt"
 
-  # file containing affirmative responses.
-  # newline separated.
+  # File containing affirmative responses. Newline separated.
   variable affirmative_responses_file "scripts/dictionary_affirmative_list.txt"
 
-  # file containing negative responses.
-  # newline separated.
+  # File containing negative responses. Newline separated.
   variable negative_responses_file "scripts/dictionary_negative_list.txt"
 
-  # file containing chatty responses. these are really just random phrases
-  # for the bot to respond with assuming it has been addressed in some
-  # way and has nothing really to say about it.
-  # newline separated.
+  # File containing chatty responses.
+  #
+  # These are really just random phrases
+  # for the bot to respond with assuming it has been addressed in some way and
+  # has nothing really to say about it. Newline separated.
   variable chatty_responses_file "scripts/dictionary_chatty_list.txt"
 
-  # time to not respond to the same word in the same channel. this is
+  # Time to not respond to the same word in the same channel. This is
   # so we don't respond to the same word in quick succession.
-  # 5 minutes.
-  variable throttle_time 300
-
-  # dictionary terms. dict file.
-  # each key is a term and associates with another dict.
-  # the sub-dict has keys:
-  # def, the definition
-  # include_term_in_def, which controls whether we output "<term> is <def>"
+  variable throttle_time [expr 10*60]
+
+  # Dictionary terms.
+  #
+  # Each key is a term and associates with another dict.
+  #
+  # The sub-dict has keys:
+  # - def, the definition
+  # - include_term_in_def, which controls whether we output "<term> is <def>"
   #   or just "<def>"
   variable terms [dict create]
 
-  # nicks to not respond to terms for. e.g., bots.
+  # Nicks to not respond to terms for. e.g., bots.
   variable skip_nicks [list]
 
-  # list of affirmative responses.
   variable affirmative_responses [list]
-
-  # list of negative responses.
   variable negative_responses [list]
+  variable chatty_responses [list]
 
-  # dict with keys <channel><term> with values containing
-  # the unixtime the last time the term was output, if any.
-  # this is for throttling term outputs.
+  # Dict with keys <channel><term> with values containing the unixtime the last
+  # time the term was output, if any.
+  #
+  # This is for throttling term outputs.
   variable flood [dict create]
 
   bind pubm -|- "*"          ::[namespace current]::public
@@ -79,7 +75,7 @@ namespace eval dictionary {
   setudef flag dictionary
 }
 
-# respond to terms in the channel
+# Respond to terms in the channel
 proc ::dictionary::public {nick host hand chan argv} {
   variable flood
   variable terms
@@ -297,12 +293,11 @@ proc ::dictionary::quotemeta {s} {
 }
 
 proc ::dictionary::get_random_response {responses nick} {
-  # we assume we have responses in the list.
+  # We assume we have responses in the list.
 
   set response_index [rand [llength $responses]]
   set response [lindex $responses $response_index]
 
-  # replace %%nick%% with %%nick%% if present.
   return [regsub -all -- "%%nick%%" $response $nick]
 }
 
@@ -330,7 +325,7 @@ proc ::dictionary::get_chatty_response {nick} {
     $::dictionary::chatty_responses $nick]
 }
 
-# load the term database from our data file.
+# Load the term database from our data file.
 proc ::dictionary::load_terms {} {
   variable term_file
   variable terms
@@ -345,14 +340,16 @@ proc ::dictionary::load_terms {} {
   return $count
 }
 
-# load contents of a file into a list.
-# each line of the file is made into one element in the list.
-# blank lines are skipped.
+# Load contents of a file into a list.
+#
+# Each line of the file is made into one element in the list.
 #
-# path: path to the file to open
+# Blank lines are skipped.
 #
-# returns: if we do not find the file or we can't open it then we return an
-#   empty list.
+# Path: Path to the file to open
+#
+# Returns: If we do not find the file or we can't open it then we return an
+# empty list.
 proc ::dictionary::file_contents_to_list {path} {
   if {![file exists $path]} {
     return [list]
@@ -374,47 +371,36 @@ proc ::dictionary::file_contents_to_list {path} {
   return $l
 }
 
-# load a list of nicks to skip from a data file.
-#
-# returns: void
+# Load a list of nicks to skip from a data file.
 proc ::dictionary::load_skip_nicks {} {
   set ::dictionary::skip_nicks [::dictionary::file_contents_to_list \
     $::dictionary::skip_nick_file]
 }
 
-# load affirmative responses from data file.
-#
-# returns: void
+# Load affirmative responses from data file.
 proc ::dictionary::load_affirmative_responses {} {
   set ::dictionary::affirmative_responses [::dictionary::file_contents_to_list \
     $::dictionary::affirmative_responses_file]
 }
 
-# load negative responses from data file.
-#
-# returns: void
+# Load negative responses from data file.
 proc ::dictionary::load_negative_responses {} {
   set ::dictionary::negative_responses [::dictionary::file_contents_to_list \
     $::dictionary::negative_responses_file]
 }
 
-# load chatty responses from data file.
-#
-# returns: void
+# Load chatty responses from data file.
 proc ::dictionary::load_chatty_responses {} {
   set ::dictionary::chatty_responses [::dictionary::file_contents_to_list \
     $::dictionary::chatty_responses_file]
 }
 
-# load data from our data files into memory.
+# Load data from our data files into memory.
 proc ::dictionary::load {args} {
-  # the term database.
   set term_count [::dictionary::load_terms]
 
-  # nicks to skip.
   ::dictionary::load_skip_nicks
 
-  # responses.
   ::dictionary::load_affirmative_responses
   ::dictionary::load_negative_responses
   ::dictionary::load_chatty_responses
@@ -422,7 +408,7 @@ proc ::dictionary::load {args} {
   return $term_count
 }
 
-# save the term/definitions to the data file.
+# Save the terms and definitions to the data file.
 proc ::dictionary::write_db {} {
   variable term_file
   variable terms
@@ -435,7 +421,7 @@ proc ::dictionary::write_db {} {
   close $fp
 }
 
-# handle save events.  write out our data files.
+# Handle save events. Write out our data files.
 proc ::dictionary::save {args} {
   ::dictionary::write_db
 }