From 8bd9f93632b411007f440dde3cfe94e0b1418b72 Mon Sep 17 00:00:00 2001 From: reality Date: Sat, 29 Dec 2012 23:05:16 +0000 Subject: [PATCH] add readme files for command and quotes [#75] --- README.md | 43 ++----------------------- modules/command/README.md | 14 ++++++++ modules/quotes/README.md | 68 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 85 insertions(+), 40 deletions(-) create mode 100644 modules/command/README.md create mode 100644 modules/quotes/README.md diff --git a/README.md b/README.md index f9adc1c..861b725 100644 --- a/README.md +++ b/README.md @@ -18,53 +18,16 @@ Requirements: handles the IRC protocol. - Various modules have their own requirements also. -### JSBot +### External Modules -JSBot can be imported by running the following commands in the cloned repository: +JSBot and externally developed modules can be imported by running the following +commands in the cloned repository: git submodule init git submodule update ## Modules: -### Command - -This handles the command execution logic for DBot. - -1. Does the input match a command key in *dbot.commands* ? -2. Is there a quote category which matches the first part of the input - (*~category*)? -3. Is there a command name similar to to the first part of the input (*~name*) - in *dbot.commands*? - -This is the only module which is force loaded, even if it's not in the -configuration. - -### Quotes - -This is the original reason that DBot was created, stores and displays quotes. - -Commands: - -- _~q category_ - Display a random quote from a given category. -- _~qadd category=newquote_ - Add a new quote to the database. -- _~qstats_ - Show a list of the biggest quote categories. -- _~qsearch category needle_ - Search for a quote in a given category. -- _~rmlast [category]_ - Remove the last quote added to a given category, or the - last quote added. -- _~rm category quote_ - Remove a given quote from the given category. -- _~qcount category_ - Show the number of quotes stored in the given category. -- _~rq_ - Show a random quote from a random category. -- _~d_ - Show a quote from the category which matches the bot's name. -- _~link category_ - Create a link to the page on the web interface which displays the - given category's quotes. -- _~qprune_ - Delete empty quote categories. - -Unfortunately, this module is fairly highly coupled with certain other areas of -the program. I am working on this, but note, for example, that one can still -access quotes with the *~category* syntax even if the quotes module isn't -loaded. - ### Admin Various administration functionality such as banning users, hot-reloading the diff --git a/modules/command/README.md b/modules/command/README.md new file mode 100644 index 0000000..437f1e7 --- /dev/null +++ b/modules/command/README.md @@ -0,0 +1,14 @@ +## Command + +Handles the command execution logic for DBot. + +### Description + +1. Does the input match a command key in *dbot.commands* ? +2. Is there a quote category which matches the first part of the input + (*~category*)? +3. Is there a command name similar to to the first part of the input (*~name*) + in *dbot.commands*? + +This is the only module which is force loaded, even if it's not specified in +the configuration file. diff --git a/modules/quotes/README.md b/modules/quotes/README.md new file mode 100644 index 0000000..1f2536e --- /dev/null +++ b/modules/quotes/README.md @@ -0,0 +1,68 @@ +## Quotes + +Stores and displays quotes. + +### Description + +This is the original reason that DBot was created, stores and displays quotes. + +### Configuration + +#### rmLimit: 10 +Amount of quotes which can be removed before admin approval is required. + +### Commands + +#### ~q [category] +Display a random quote from a given category. + +#### ~qadd [category] = [quote] +Add a new quote to the database. + +#### ~qstats +Show a list of the biggest quote categories. + +#### ~qsearch [category] = [needle] +Search a category for quotes including the given text. + +#### ~rmlast [category] +Remove the last quote added to a given category. + +#### ~rmstatus +Show how many quotes are currently in the removal cache, and whether they will +be randomly removed. + +#### ~rm [category] = [quote] +Remove a given quote from the given category. + +#### ~qcount [category] +Show the number of quotes stored in the given category, or if called without a +category it will show the total number of quotes in the database. + +#### ~rq +Show a random quote from the database. + +#### ~link [category] +Show a link to the page on the web interface which shows this category's quotes. + +### Admin-only Commands + +#### ~rmconfirm +Confirm that the quotes currently in the removal cache are okay to be removed, +and permanently delete them. + +#### ~rmdeny +Re-instate the quotes that are currently in the removal cache back into the main +quote database. + +### Removal Spam Protection + +When quotes are removed using either the ~rm or ~rmlast commands, the quotes are +removed from the main database, but are stored in a removal cache which is cleared +out ten minutes from the last time a quote was removed from the database. If the +number of quotes removed from the database reaches a certain limit (as per rmLimit +in config, default 10) then the counter is removed and the cache will not be deleted +automatically. In such a case, a DBot admin needs to either run the ~rmconfim command +to have the removal cache cleared, or ~rmdeny to re-instate all of the quotes in +the removal cache back into the main quote database. This is to stop mass +removal from the database without limiting the user interface.