chore(docs): fix #1813 and other doc inconsistencies (#1821)

Co-authored-by: Joey Guerra <joey@joeyguerra.com>

Author: joeyguerra

docs/patterns.md

@@ -29,11 +29,11 @@ Setting this up is very easy:
 //  Commands:
 //    None
 
-module.exports = (robot) => {
-  robot.hear(/^hubot:? (.+)/i, (res) => {
+export default async (robot) => {
+  robot.hear(/^hubot:? (.+)/i, async (res) => {
     let response = `Sorry, I'm a diva and only respond to ${robot.name}`
     response += robot.alias ? ` or ${robot.alias}` : ''
-    return res.reply(response)
+    return await res.reply(response)
   })
 }
 ```
@@ -63,9 +63,9 @@ Here is the setup:
 // Commands:
 //   None
 //
-module.exports = (robot) => {
-  robot.respond(/help\s*(.*)?$/i, (res) => {
-    return res.reply('That means nothing to me anymore. Perhaps you meant "docs" instead?')
+export default async (robot) => {
+  robot.respond(/help\s*(.*)?$/i, async (res) => {
+    return await res.reply('That means nothing to me anymore. Perhaps you meant "docs" instead?')
   })
 }
 
@@ -80,26 +80,30 @@ To do this, you can set up a lock in the Hubot [brain](scripting.html#persistenc
 Setting up the lock looks something like this:
 
 ```javascript
-module.exports = (robot) => {
-  robot.brain.on('loaded', ()=>{
+export default async (robot) => {
+  robot.brain.on('loaded', () => {
     // Clear the lock on startup in case Hubot has restarted and Hubot's brain has persistence (e.g. redis).
     // We don't want any orphaned locks preventing us from running commands.
     robot.brain.remove('yourLockName')
-  }
+  })
 
-  robot.respond(/longrunningthing/i, (msg) => {
+  robot.respond(/longrunningthing/i, async (msg) => {
     const lock = robot.brain.get('yourLockName')
     if (lock) {
-      return msg.send(`I'm sorry, ${msg.message.user.name}, I'm afraid I can't do that. I'm busy doing something for ${lock.user.name}.`)
+      return await msg.send(`I'm sorry, ${msg.message.user.name}, I'm afraid I can't do that. I'm busy doing something for ${lock.user.name}.`)
     }
 
     robot.brain.set('yourLockName', msg.message)  // includes user, room, etc about who locked
 
-    yourLongClobberingAsyncThing(err, res).then(
+    try {
+      await yourLongClobberingAsyncThing()
       // Clear the lock
       robot.brain.remove('yourLockName')
-      msg.reply('Finally Done')
-    )).catch(e => console.error(e))
+      await msg.reply('Finally Done')
+    } catch (e) {
+      console.error(e)
+    }
+  })
 }
 ```
 
@@ -114,8 +118,8 @@ Due to the way Node.js handles HTTP and HTTPS requests, you need to specify a di
 3. Add the following code, modified for your needs:
 
 ```javascript
-const proxy = require('proxy-agent')
-module.exports = (robot) => {
+import proxy from 'proxy-agent'
+export default async (robot) => {
   robot.globalHttpOptions.httpAgent  = proxy('http://my-proxy-server.internal', false)
   robot.globalHttpOptions.httpsAgent = proxy('http://my-proxy-server.internal', true)
 }
@@ -133,8 +137,8 @@ For example, the [factoid lookup command](https://github.com/github/hubot-script
 // use case: Hubot>fact1
 // This listener doesn't require you to type the bot's name first
 
-const {TextMessage} = require('../src/message')
-module.exports = (robot) => {
+import {TextMessage} from '../src/message.mjs'
+export default async (robot) => {
     // Dynamically populated list of factoids
     const facts = {
         fact1: 'stuff',
@@ -157,9 +161,9 @@ module.exports = (robot) => {
             }
         },
         // Callback
-        (res) => {
+        async (res) => {
             const fact = res.match
-            res.reply(`${fact} is ${facts[fact]}`)
+            await res.reply(`${fact} is ${facts[fact]}`)
         }
     )
 }
@@ -207,28 +211,28 @@ const POWER_USERS = [
     'Shell' // String that matches the user ID set by the adapter
 ]
 
-module.exports = (robot) => {
-  robot.listenerMiddleware((context, next, done) => {
+export default async (robot) => {
+  robot.listenerMiddleware(async (context) => {
       if (POWER_COMMANDS.indexOf(context.listener.options.id) > -1) {
           if (POWER_USERS.indexOf(context.response.message.user.name) > -1){
               // User is allowed access to this command
-              next()
+              return true
           } else {
               // Restricted command, but user isn't in whitelist
-              context.response.reply(`I'm sorry, @${context.response.message.user.name}, but you don't have access to do that.`)
-              done()
+              await context.response.reply(`I'm sorry, @${context.response.message.user.name}, but you don't have access to do that.`)
+              return false
           }
       } else {
           // This is not a restricted command; allow everyone
-          next()
+          return true
       }
   })
 
   robot.listen(message => {
       return true
   }, {id: 'deploy.web'},
-  res => {
-      res.reply('Deploying web...')
+  async res => {
+      await res.reply('Deploying web...')
   })
 }
 ```

docs/scripting.md

@@ -842,7 +842,7 @@ Every middleware receives the same API signature of `context`. Different kinds o
 
 Asynchronous middleware should catch its own exceptions, emit an `error` event, and return `true` or `false`. Any uncaught exceptions will interrupt all execution of middleware.
 
-# <a name="listener-middleware">Listener Middleware</a>
+## Listener Middleware
 
 Listener middleware inserts logic between the listener matching a message and the listener executing. This allows you to create extensions that run for every matching script. Examples include centralized authorization policies, rate limiting, logging, and metrics. Middleware is implemented like other hubot scripts: instead of using the `hear` and `respond` methods, middleware is registered using `listenerMiddleware`.
 
@@ -965,21 +965,39 @@ Response middleware runs against every message hubot sends to a chat room. It's
 
 ## Response Middleware Example
 
-This simple example changes the format of links sent to a chat room from markdown links (like [example](https://example.com)) to the format supported by [Slack](https://slack.com), <https://example.com|example>.
+Response middleware allows you to intercept and modify outgoing messages before they're sent to the chat room. The `context.strings` array contains the actual message text that will be sent.
+
+This example changes the format of links from markdown links (like [example](https://example.com)) to the format supported by [Slack](https://slack.com), <https://example.com|example>:
 
 ```javascript
 // .mjs
-export default async robot=> {
-  robot.responseMiddleware(async context=> {
-    if(!context.plaintext) return true
-    context.strings.forEach(string => {
-      string.replace(/\[([^\[\]]*?)\]\((https?:\/\/.*?)\)/, "<$2|$1>"
+export default async robot => {
+  robot.responseMiddleware(async context => {
+    // Only process plaintext messages (send, reply, etc.)
+    if (!context.plaintext) return true
+    
+    // Modify each string in the response
+    context.strings = context.strings.map(string => {
+      // Convert markdown links to Slack format
+      return string.replace(/\[([^\[\]]*?)\]\((https?:\/\/.*?)\)/, "<$2|$1>")
     })
+    
     return true
   })
 }
 ```
 
+## How to Use Response Middleware
+
+Response middleware is called every time a message is sent from a listener. Key points:
+
+- Access the outgoing message strings via `context.strings` - this is an array of strings being sent
+- Modify the strings by reassigning `context.strings` or mapping over the array
+- The `context.method` tells you how the message was sent (`send`, `reply`, `emote`, etc.)
+- Return `true` to allow the message to continue to the adapter, or `false` to stop it
+- Be careful not to create infinite loops by sending new messages from middleware, as they will also trigger middleware
+- Use `context.plaintext` to distinguish between regular messages and other message types
+
 ## Response Middleware API
 
 Response middleware callbacks receive 1 parameters, `context` and are Promises/async/await. Receive middleware context includes these fields: