Skip to content

Massive header docs update #468

Merged
merged 37 commits into from Jun 24, 2012

4 participants

@tombell
tombell commented Jun 8, 2012

Reformatting the header comment at the top of each script to simplify and provide useful information for configuring/dependencies.

Preferably refrain for merging in pull requests until this update is finished.

WIP.

@technicalpickles
GitHub member

I started apply this to hubot's src/scripts. After a few, having headings for things that were None seemed like noise. Except maybe description, which probably should be a real description.

Also, a few new headings I encountered needing:

  • URLs: for routing stuff
  • Examples: for examples of commands, when it's not obvious how to use
@tombell
tombell commented Jun 9, 2012

I thought about leaving None so services like the hubot-scripts-catalog can easily parse it. When I've finished updating the rest, we can maybe work out what needs adding and what doesn't.

@technicalpickles
GitHub member

Template for copy-pasta into scripts:

# Description:
#   None
#
# Dependencies:
#   None
#
# Configuration:
#   None
#
# Commands:
#   None
#
# Author:
#   None

Also, this may be me being picky, but not a fan of the leading/trailing lines.

@tombell
tombell commented Jun 9, 2012

Me either, I was gonna remove them.

@technicalpickles
GitHub member

I was thinking about Configuration, and it probably would be good to have notes about what they are. The aws.coffee had this, and so does wunderlist.coffee which I'm looking at now. I could imagine something like hubot help configuration listing out all these environment variables and what they are for. Those shouldn't show up for hubot help for commands though.

Having 'help commands' be any line with a - can be kind of annoying, especially if you have stuff legitimately hyphenated words. It also means that HUBOT_WUNDERLIST_SMTP_HOST - your smtp host e.g. smtp.gmail.com would match, even if it's not a command. For this case at least, I think we can update hubot to skip over lines that start with HUBOT_.

@tombell
tombell commented Jun 9, 2012

Maybe update hubot to read and parse the header comments and store the relevant pieces of info for help stuff.

@tombell
tombell commented Jun 9, 2012

Oof. Think that's me done for the night, you fancy finishing off the last few letters?

@technicalpickles
GitHub member

There's just s and t left. Of course, there's 47 between them... I'll see how far I can get on em.

@technicalpickles
GitHub member

Calling it night. Just 's' left now. Give a shout if/when you pick back up on these.

@stevenh512

Should this None be here? 😁

GitHub member

None. I mean... Nope. If this is the only one I missed after updating all these comments, then I will be quite pleased.

Not 100% sure.. but I think this is the only one.

@tombell
tombell commented Jun 9, 2012

I'll work on 's' today.

@tombell
tombell commented Jun 9, 2012

I think we're done!

@sirkitree

Wow, great job guys! I just saw this and I'm pretty damn happy about it. :) Reviewing...

@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/9gag.coffee
@@ -1,7 +1,18 @@
-# hubot 9gag me - Returns a random meme image.
-
-# Random meme from 9gag
-# Rewrite by Enrique Vidal
+# Description:
+# None
@sirkitree
sirkitree added a note Jun 10, 2012

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

@technicalpickles
GitHub 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/abstract.coffee
-# 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
@sirkitree
sirkitree added a note Jun 10, 2012

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

@technicalpickles
GitHub 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.

@tombell
tombell added a note Jun 11, 2012

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.

@sirkitree
sirkitree added a note Jun 11, 2012

I have to agree with @tombell here.

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

@technicalpickles
GitHub 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/achievement_unlocked.coffee
@@ -1,6 +1,18 @@
+# Description:
+# None
@sirkitree
sirkitree added a note Jun 10, 2012

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/ackbar.coffee
@@ -1,7 +1,17 @@
-# It's a trap
+# Description:
+# None
@sirkitree
sirkitree added a note Jun 10, 2012

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/auto-stache.coffee
#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
+# None
@sirkitree
sirkitree added a note Jun 10, 2012

Commands: None? Shouldn't this be required?

@technicalpickles
GitHub member

Not strictly speaking. You can have scripts that are just doing routing stuff, for example. In this case, 'command' isn't really accurate. It's more the things it will hear and respond to, ie URLs with png, jpg, gif.

@tombell
tombell added a note Jun 11, 2012

Here the description will suffice, commands imply something you type to trigger it, where as this just detects URLs.

@sirkitree
sirkitree added a note Jun 11, 2012

Yeah, I think there are a few that listen for particular things. In this case an image. I wonder if cases here it's more of a listener than a command that we can list that, perhaps in notes? This one is probably explanatory enough within the description.

@tombell
tombell added a note Jun 11, 2012

Might be a better option to rename Commands: to Triggers: which will cover everything. Thoughts?

@sirkitree
sirkitree added a note Jun 11, 2012

++

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/aws.coffee
#
-# package.json needs to have "aws2js":"0.6.12" and "moment":"1.6.2" and "underscore":"1.3.3"
+# Commands:
+# hubot sqs status - Returns the status of SQS queues
@sirkitree
sirkitree added a note Jun 10, 2012

Think we're missing a command here. Looks like the original doc header had two commands.

# hubot sqs status - Returns the status of SQS queues.
# hubot ec2 status - Returns the status of EC2 instances.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/conversation.coffee
@@ -1,4 +1,17 @@
-# Extends robot adding conversation features
+# Description:
+# Extends robot adding conversation features
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
+# None
@sirkitree
sirkitree added a note Jun 10, 2012

Another Commands: None
Perhaps this is another area for a separate issue? "Find all scripts not listing a command and document the command?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/demolition-man.coffee
@@ -1,4 +1,16 @@
-# Watch your language!
+# Description:
+# Watch your language!
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command doc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/eval.coffee
@@ -1,6 +1,17 @@
-# evaluate code.
+# Description:
+# evaluate code
@sirkitree
sirkitree added a note Jun 10, 2012

LOL - wow, this just sounds like a terrible idea - what the heck are the standards for allowing a script in? Whoa.

@tombell
tombell added a note Jun 10, 2012

Eval's code on a web service, not the hubot, so there is no issue really.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/facepalm.coffee
@@ -1,5 +1,16 @@
-# Clearly illustrate with an image what people mean whenever
-# they say "facepalm".
+# Description:
+# Clearly illustrate with an image what people mean whenever they say "facepalm"
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command doc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/file-brain.coffee
@@ -1,8 +1,21 @@
+# Description:
+# None
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# FILE_BRAIN_PATH
+#
+# Commands:
+# None
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command and description docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/flying-high.coffee
@@ -1,3 +1,17 @@
+# Description:
+# None
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command and description docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree and 1 other commented on an outdated diff Jun 10, 2012
src/scripts/github-issues.coffee
#
-# You need to set the following variable:
-# HUBOT_GITHUB_TOKEN = "<oauth token>"
+# Dependencies:
+# "underscore": "1.3.3"
+# "underscore": "2.1.1"
@sirkitree
sirkitree added a note Jun 10, 2012

this relies on 2 versions of underscore? is that even possible?

@tombell
tombell added a note Jun 10, 2012

the 2nd one is suppose to be underscore.string.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/inigo-montoya.coffee
@@ -1,3 +1,17 @@
+# Description:
+# None
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command and description docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/itcrowd.coffee
-
-# REQUIRED MODULES
-# sudo npm install htmlparser
-# sudo npm install soupselect
-# sudo npm install jsdom
-# sudo npm install underscore
+# Dependencies:
+# "htmlparser": "1.7.6"
+# "soupselect: "0.2.0"
+# "jsdom": "0.2.14"
+# "underscore": "1.3.3"
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/jira.coffee
-# hubot show filter(s) - Show all filters
-# hubot show filter <name> - Show a specific filter
-
-# Required environment variables:
-# * HUBOT_JIRA_URL: Base URL to JIRA instance, without trailing slash eg: https://myserver.com/jira
-# * HUBOT_JIRA_USER: JIRA username
-# * HUBOT_JIRA_PASSWORD: JIRA password
-# Optional environment variables:
-# * HUBOT_JIRA_USE_V2: "true" to use v2 of the JIRA REST API, defaults to "false" (v1)
-# * HUBOT_JIRA_MAXLIST: maximum number of items to show for a JQL query, defaults to 10
-# * HUBOT_JIRA_ISSUEDELAY: number of seconds to not show a ticket for again after it's been
-# mentioned once. This helps to cut down on noise from the bot.
-# Defaults to 30.
-# * HUBOT_JIRA_IGNOREUSERS: Comma-seperated list of users to ignore "hearing" issues from.
-# This works well with other bots or API calls that post to the room.
-# Example: "Subversion,TeamCity,John Doe"
@sirkitree
sirkitree added a note Jun 10, 2012

There are quite a few of these where the description for keys is removed. IMHO it might be good to keep these somehow. Either as they are (with the config vars) or in the Notes section.

@tombell
tombell added a note Jun 10, 2012

Not 100% certain on what the formatting of the help for keys is going to be like, they can be retrofitted once formatting is done.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/jordan.coffee
@@ -1,5 +1,17 @@
-# Display a picture of Michael Jordan if anyone invokes "jordan" or says "23"
-# Cause Jordan is God. So much more than Steve Jobs :D
+# Description:
+# Display a picture of Michael Jordan if anyone invokes "jordan" or says "23"
+# Cause Jordan is God. So much more than Steve Jobs :D
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Description says it all, so command doc being blank here might be ok?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/likeaboss.coffee
#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/linsanity.coffee
@@ -1,5 +1,17 @@
-# Display a picture of Jeremy Lin if anyone invokes "linsanity" or says "linspire"
-# Cause Lin is Linspiring!
+# Description:
+# Display a picture of Jeremy Lin if anyone invokes "linsanity" or
+# says "linspire". Cause Lin is Linspiring!
+#
+# Dependecies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Command blank here too, but description says it's more of a listener.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@tombell
tombell commented Jun 10, 2012

The commands are basically me not bothering to read a script and work out what everything does, I only added the commands for scripts that already had them documented.

@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/myappstatus.coffee
# setup http://hostname/hubot/myappstatus/ROOMNUMBER as
# your notification webook. If on Heroku lookup the hostname where
# the hubot server is running. (e.g. my-hubot.herokuapp.com)
#
-# Check you are using a recent version of hubot in packages.json
-# to ensure the robot.router is available
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing commands doc and nothing says anything about what it keys off of.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/ping.coffee
@@ -1,4 +1,16 @@
-# Hubot is very attentive (ping hubot)
+# Description:
+# Hubot is very attentive (ping hubot)
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command docs. Is 'ping hubot' the command?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/polite.coffee
#
-# Say thanks to your robot.
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/put-it-back.coffee
@@ -1,4 +1,16 @@
-# put back the table
+# Description:
+# put back the table
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
+#
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/redis-brain.coffee
@@ -1,3 +1,18 @@
+# Description:
+# None
+#
+# Dependencies:
+# "redis": "0.7.2"
+#
+# Configuration:
+# REDISTOGO_URL
+#
+# Commands:
+# None
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command and description docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/sensitive.coffee
@@ -1,4 +1,16 @@
-# Hubot has feelings too, you know
+# Description:
+# Hubot has feelings too, you know
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command docs and desc gives you no clue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/serenity.coffee
@@ -1,4 +1,16 @@
-# Serenity Now!!
+# Description:
+# Serenity Now!!
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command docs and desc gives you no clue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/sigh.coffee
@@ -1,4 +1,16 @@
-# http://xkcd.com/1009/
+# Description:
+# http://xkcd.com/1009/
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command docs and desc gives you no clue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/store-messages-couchdb.coffee
@@ -1,3 +1,18 @@
+# Description:
+# None
+#
+# Dependencies:
+# "cradle": "0.6.3"
+#
+# Configuration:
+# HUBOT_COUCHDB_URL
+#
+# Commands:
+# None
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command docs and desc gives you no clue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/sweetdude.coffee
@@ -1,3 +1,17 @@
+# Description:
+# None
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
+#
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command docs and desc gives you no clue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/tweet-content.coffee
@@ -1,4 +1,17 @@
-# detect tweet URL and send tweet content
+# Description:
+# None
+#
+# Dependencies:
+# None
+#
+# Configuration:
+# None
+#
+# Commands:
@sirkitree
sirkitree added a note Jun 10, 2012

Missing command docs and description (mistakenly?) removed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on an outdated diff Jun 10, 2012
src/scripts/wikipedia.coffee
+# 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.
@sirkitree
sirkitree added a note Jun 10, 2012

Should this really be in here? Shouldn't any script to be included be part of the overall and only one determined license?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@sirkitree sirkitree commented on the diff Jun 10, 2012
src/scripts/xmas.js
//
+// Configuration:
+// None
+//
+// Commands:
+// hubot is it xmas ? - returns whether is it christmas or not
+// hubot is it christmas ? - returns whether is it christmas or not
+//
+// Author:
+// Johnny G. Halife
@sirkitree
sirkitree added a note Jun 10, 2012

Why does this one have different comment notation?

@tombell
tombell added a note Jun 10, 2012

It's JavaScript.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@tombell
tombell commented Jun 11, 2012
# Description:
#   <description of the script functionality>
#
# Dependencies:
#   "<module-name>": "<module-version>"
#
# Configuration:
#   ENV_VAR_1: <what the environment variable is>
#
# Triggers:
#   <respond/hear trigger> - <description of the functionality for the trigger>
#
# Notes:
#   <optional notes about the script, including finding values for environment variables and setup>
#
# Routes:
#   <GET/PUT/POST/DELETE route> - <description of what the route does>
#
# Author:
#   <author's github username>
@tombell
tombell commented Jun 19, 2012

I'm going to give this another once through changing Commands: to Triggers:, then I'm going to merge into master. Anything people disagree with then can be opened in separate issues/pull requests.

@tombell tombell merged commit 9b6ec36 into master Jun 24, 2012
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.