This repository has been archived by the owner. It is now read-only.

Massive header docs update #468

Merged
merged 37 commits into from Jun 24, 2012
Commits
Jump to file or symbol
Failed to load files and symbols.
+3,840 −1,328
Diff settings

Always

Just for now

View
@@ -1,7 +1,13 @@
# hubot-scripts
-These are a collection of community scripts for
-[Hubot](https://github.com/github/hubot), a chat bot for your company.
+These are a collection of community scripts for [hubot][hubot], a chat bot for
+your company.
+
+
+## Discovering
+
+Check out the [hubot-script-catalog][script-catalog] for a list and description
+of all the available scripts.
## Installing
@@ -10,33 +16,67 @@ right into your generated Hubot installation. Just put them in `scripts`, add
the new scripts to the `hubot-scripts.json` file.
Any third-party dependencies for scripts need adding your your `package.json`
-otherwise a lot of errors will be thrown during the start up of your hubot.
+otherwise a lot of errors will be thrown during the start up of your hubot. You
+can find a list of dependencies for a script in the documentation header at the
+top of the script.
Restart your robot, and you're good to go.
-All the scripts in this repository are located in
-[`src/scripts`](https://github.com/github/hubot-scripts/tree/master/src/scripts).
+All the scripts in this repository are located in [`src/scripts`][src-scripts].
## Writing
Want to write your own Hubot script? The best way is to take a look at an
-[existing script](https://github.com/github/hubot-scripts/blob/master/src/scripts/tweet.coffee)
-and see how things are set up. Hubot scripts are written in CoffeeScript, a
-higher-level implementation of JavaScript.
+[existing script][example-script] and see how things are set up. Hubot scripts
+are written in CoffeeScript, a higher-level implementation of JavaScript.
-You'll also want to [add tests](https://github.com/github/hubot-scripts/blob/master/test/tests.coffee)
-for your script; no one likes untested code. It makes Hubot sad.
+You'll also want to [add tests][hubot-script-tests] for your script; no one
+likes untested code. It makes Hubot sad.
-Additionally, it's extremely helpful to add [TomDoc](http://tomdoc.org) to the
-top of each file. (Check out [an example](https://github.com/github/hubot-scripts/blob/master/src/scripts/speak.coffee#L1-5)).
-We'll pull out the commands from those lines and display them in the generic,
-robot-wide `hubot help` command.
+Additionally, it's extremely helpful to add [TomDoc][tomdoc] to the top of each
+file. (Check out [an example][example-script-doc]). We'll pull out the commands
+from those lines and display them in the generic, robot-wide `hubot help`
+command.
Please note we're no longer including external dependencies in the
`package.json`, so should you wish to include them please include the package
name and required version in the TomDoc comments at the top of your script.
-## Discovering
+## Documentation
+
+We're now requiring all scripts in hubot-scripts to contain a documentation
+header so people know every thing about the script.
+
+```coffeescript
+# Description
+# <description of the scripts functionality>
+#
+# Dependencies:
+# "<module name>": "<module version>"
+#
+# Configuration:
+# LIST_OF_ENV_VARS_TO_SET
+#
+# Commands:
+# hubot <trigger> - <what the respond trigger does>
+# <trigger> - <what the hear trigger does>
+#
+# Notes:
+# <optional notes required for the script>
+#
+# Author:
+# <github username of the original script author>
+```
-[The Script Catalog](http://hubot-script-catalog.herokuapp.com/)
+If you have nothing to fill in for a section you should include `None` in that
+section. Empty sections which are optional should be left blank. A script will
+be required to fill out the documentation before being merged into the
+repository.
+[hubot]: https://github.com/github/hubot
+[script-catalog]: http://hubot-script-catalog.herokuapp.com
+[src-scripts]: https://github.com/github/hubot-scripts/tree/master/src/scripts
+[tomdoc]: http://tomdoc.org
+[example-script]: https://github.com/github/hubot-scripts/blob/master/src/scripts/tweet.coffee
+[hubot-script-tests]: https://github.com/github/hubot-scripts/blob/master/test/tests.coffee
+[example-script-docs]: (https://github.com/github/hubot-scripts/blob/master/src/scripts/speak.coffee#L1-5
View
@@ -1,10 +1,20 @@
-# Allows Hubot to send text messages using 46elks.com API.
+# Description:
+# Allows Hubot to send text messages using 46elks.com API.
#
-# you need to set HUBOT_46ELKS_USERNAME and HUBOT_46ELKS_PASSWORD
+# Dependencies:
+# None
#
-# hubot sms <user> <message> - Sends <message> to the number <to>.
-# hubot <user> has phone number <phone> - Sets the phone number of <user> to <phone>.
-# hubot give me the phone number to <user> - Gets the phone number of <user>.e
+# Configuration:
+# HUBOT_46ELKS_USERNAME
+# HUBOT_46ELKS_PASSWORD
+#
+# Commands:
+# hubot sms <user> <message> - Sends <message> to the number <to>
+# hubot <user> has phone number <phone> - Sets the phone number of <user> to <phone>
+# hubot give me the phone number to <user> - Gets the phone number of <user>
+#
+# Author:
+# kimf
QS = require "querystring"
module.exports = (robot) ->
View
@@ -1,7 +1,18 @@
-# hubot 9gag me - Returns a random meme image.
-
-# Random meme from 9gag
-# Rewrite by Enrique Vidal
+# Description:
+# None

This comment has been minimized.

@sirkitree

sirkitree Jun 10, 2012

Contributor

You could probably put the description here to be "Returns a random meme image", but not a huge deal I think.

@sirkitree

sirkitree Jun 10, 2012

Contributor

You could probably put the description here to be "Returns a random meme image", but not a huge deal I think.

This comment has been minimized.

@technicalpickles

technicalpickles Jun 11, 2012

Member

For scripts that are a single trigger, with the help command being enough to explain it, I almost think Description isn't really necessary. It's just copy-pasta, that doesn't add anything compared to the usage.

@technicalpickles

technicalpickles Jun 11, 2012

Member

For scripts that are a single trigger, with the help command being enough to explain it, I almost think Description isn't really necessary. It's just copy-pasta, that doesn't add anything compared to the usage.

+#
+# Dependencies:
+# "htmlparser": "1.7.6"
+# "soupselect: "0.2.0"
+#
+# Configuration:
+# None
+#
+# Commands:
+# hubot 9gag me - Returns a random meme image
+#
+# Author:
+# EnriqueVidal
Select = require( "soupselect" ).select
HTMLParser = require "htmlparser"
@@ -1,27 +1,17 @@
-# hubot abstract <topic> - Prints a nice abstract of the given topic.
-
-# Copyright (c) 2011 John Tantalo
-#
-# Permission is hereby granted, free of charge, to any person
-# obtaining a copy of this software and associated documentation
-# files (the "Software"), to deal in the Software without
-# restriction, including without limitation the rights to use,
-# copy, modify, merge, publish, distribute, sublicense, and/or sell
-# copies of the Software, and to permit persons to whom the
-# Software is furnished to do so, subject to the following
-# conditions:
-#
-# The above copyright notice and this permission notice shall be
-# included in all copies or substantial portions of the Software.
-#
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
-# OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
-# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-# WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-# OTHER DEALINGS IN THE SOFTWARE.
+# Description:
+# None

This comment has been minimized.

@sirkitree

sirkitree Jun 10, 2012

Contributor

Again, here the description could be "Prints a nice abstract of the given topic"

@sirkitree

sirkitree Jun 10, 2012

Contributor

Again, here the description could be "Prints a nice abstract of the given topic"

This comment has been minimized.

@technicalpickles

technicalpickles Jun 11, 2012

Member

It's also a little fuzzy if we should be removing licensing stuff that people add to their scripts. Or, we have to assume they are being made under hubot-script's license, and remove it from all the scripts that have it.

@technicalpickles

technicalpickles Jun 11, 2012

Member

It's also a little fuzzy if we should be removing licensing stuff that people add to their scripts. Or, we have to assume they are being made under hubot-script's license, and remove it from all the scripts that have it.

This comment has been minimized.

@tombell

tombell Jun 11, 2012

Contributor

When people usually contribute to an open source project the license is usually the one of the actual project. If the license differs to the hubot-scripts license, then people should release the script in it's own package in my opinion.

@tombell

tombell Jun 11, 2012

Contributor

When people usually contribute to an open source project the license is usually the one of the actual project. If the license differs to the hubot-scripts license, then people should release the script in it's own package in my opinion.

This comment has been minimized.

@sirkitree

sirkitree Jun 11, 2012

Contributor

I have to agree with @tombell here.

It should probably be part of the submission guidelines or something. Are there any actually?

@sirkitree

sirkitree Jun 11, 2012

Contributor

I have to agree with @tombell here.

It should probably be part of the submission guidelines or something. Are there any actually?

This comment has been minimized.

@technicalpickles

technicalpickles Jun 11, 2012

Member

Sounds good to me. There isn't a guideline, but there should be. The README is going to be the best place for that, I think.

@technicalpickles

technicalpickles Jun 11, 2012

Member

Sounds good to me. There isn't a guideline, but there should be. The README is going to be the best place for that, I think.

+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
+# hubot abstract <topic> - Prints a nice abstract of the given topic
+#
+# Author:
+# tantalor
module.exports = (robot) ->
robot.respond /(abs|abstract) (.+)/i, (res) ->
@@ -1,6 +1,18 @@
+# Description:
+# None

This comment has been minimized.

@sirkitree

sirkitree Jun 10, 2012

Contributor

This could actually use a description, but should probably be a separate issue. i have no idea what the heck this does from reading the header.

@sirkitree

sirkitree Jun 10, 2012

Contributor

This could actually use a description, but should probably be a separate issue. i have no idea what the heck this does from reading the header.

#
-# hubot achievement get <achievement> [achiever's gravatar email] - life goals are in reach.
+# Dependencies:
+# None
#
+# Configuration:
+# None
+#
+# Commands:
+# hubot achievement get <achievement> [achiever's gravatar email] - life goals are in reach
+#
+# Author:
+# Chris
+
module.exports = (robot) ->
robot.hear /achievement (get|unlock(ed)?) (.+?)(\s*[^@\s]+@[^@\s]+)?\s*$/i, (msg) ->
caption = msg.match[3]
View
@@ -1,7 +1,17 @@
-# It's a trap
+# Description:
+# None

This comment has been minimized.

@sirkitree

sirkitree Jun 10, 2012

Contributor

Seems there are quite a lot of blank descriptions or the description is in the command. Perhaps a separate pull request once the formatting is at least in place would be warranted instead of pointing them all out here.

@sirkitree

sirkitree Jun 10, 2012

Contributor

Seems there are quite a lot of blank descriptions or the description is in the command. Perhaps a separate pull request once the formatting is at least in place would be warranted instead of pointing them all out here.

#
-# trap - Display an Admiral Ackbar piece of wonder
+# Dependencies:
+# None
#
+# Configuration:
+# None
+#
+# Commands:
+# trap - Display an Admiral Ackbar piece of wonder
+#
+# Author:
+# brilliantfantastic
ackbars = [
"http://dayofthejedi.com/wp-content/uploads/2011/03/171.jpg",
View
@@ -1,5 +1,17 @@
-# Display a hyperbole and a half image if anyone says "like an adult"
+# Description:
+# None
#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
+# like an adult - Display a hyperbole and a half image
+#
+# Author:
+# atmos
images = [
"http://1.bp.blogspot.com/_D_Z-D2tzi14/TBpOnhVqyAI/AAAAAAAADFU/8tfM4E_Z4pU/s400/responsibility12(alternate).png",
@@ -15,7 +27,3 @@ images = [
module.exports = (robot) ->
robot.hear /like an adult/i, (msg) ->
msg.send msg.random images
-
-# Be an adult
-# This is Why I'll Never be an Adult:
-# Taken from: http://hyperboleandahalf.blogspot.com/2010/06/this-is-why-ill-never-be-adult.html
@@ -1,26 +1,28 @@
-# Returns error info from Airbrake
+# Description:
+# None
#
-# hubot show me airbrake errors - Get the most recent active errors
+# Dependencies:
+# "jsdom": "0.2.14"
+#
+# Configuration:
+# HUBOT_AIRBRAKE_AUTH_TOKEN
+# HUBOT_AIRBRAKE_PROJECT
+#
+# Commands:
+# hubot show me airbrake errors - Get the most recent active errors
+#
+# Author:
+# tommeier
+
jsdom = require 'jsdom'
env = process.env
-# ENV Variables required :
-# HUBOT_AIRBRAKE_AUTH_TOKEN : Auth token from your account ( Login to site and go to 'Settings' )
-# HUBOT_AIRBRAKE_PROJECT : Account name (eg: http://<account name>.airbrakeapp.com)
-
-# Add to heroku :
-# % heroku config:add HUBOT_AIRBRAKE_AUTH_TOKEN="..."
-# % heroku config:add HUBOT_AIRBRAKE_PROJECT="..."
-# Example error and further API :
-# http://help.airbrake.io/kb/api-2/api-overview
-
module.exports = (robot) ->
robot.respond /(show me )?airbrake( errors)?(.*)/i, (msg) ->
query msg, (body, err, project_name) ->
return msg.send err if err
-
error_groups = body.getElementsByTagName("group")
return msg.send "Congrats! No errors in the system right now!" unless error_groups?
@@ -79,5 +81,3 @@ module.exports = (robot) ->
catch err
err = "Could not fetch airbrake errors."
cb(body, err, airbrake_project)
-
-
View
@@ -1,6 +1,17 @@
-#display images of alots
+# Description:
+# None
#
-# alot - shows a picture of an alot
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
+# alot - Shows a picture of an alot
+#
+# Author:
+# tbwIII
images = [
"http://4.bp.blogspot.com/_D_Z-D2tzi14/S8TRIo4br3I/AAAAAAAACv4/Zh7_GcMlRKo/s400/ALOT.png",
View
@@ -1,6 +1,17 @@
-# Send messages to users the next time they speak
+# Description:
+# Send messages to users the next time they speak
#
-# hubot ambush <user name>: <message>
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
+# hubot ambush <user name>: <message>
+#
+# Author:
+# jmoses
appendAmbush = (data, toUser, fromUser, message) ->
if data[toUser.name]
View
@@ -1,7 +1,19 @@
-# Because animals are animals.
+# Description:
+# Because animals are animals.
#
-# hubot animal me - Grab a random gif from http://animalsbeingdicks.com/
+# Dependencies:
+# "htmlparser": "1.7.6"
+# "soupselect: "0.2.0"
#
+# Configuration:
+# None
+#
+# Commands:
+# hubot animal me - Grab a random gif from http://animalsbeingdicks.com/
+#
+# Author:
+# unsay
+
Select = require("soupselect").select
HtmlParser = require "htmlparser"
Oops, something went wrong.