Implement deprecation notice

Render a deprecation notice for options that have been labeled with the
JSDoc `@deprecated` tag.

Author: jugglinmike

package.json

@@ -9,9 +9,10 @@
     "build": "oddweb build ."
   },
   "dependencies": {
-    "dox": "^0.5.3",
-    "oddweb": "~0.0.4",
+    "dox": "^0.6.1",
     "jshint": "latest",
+    "marked": "^0.3.2",
+    "oddweb": "~0.0.4",
     "sqwish": "0.2.x",
     "uglify-js": "2.4.x"
   },

plugins/options.js

@@ -1,8 +1,11 @@
 "use strict";
 var fs = require("fs")
 var dox = require("dox");
+var marked = require("marked");
 
 var optionsSrc = __dirname + "/../res/jshint/src/options.js";
+var deprecationMsg = "<strong>Warning</strong> This option has been " +
+  "deprecated and will be removed in the next major release of JSHint."
 
 dox.setMarkedOptions({
   breaks: false
@@ -38,12 +41,31 @@ function getCategory(annotation) {
   return name;
 }
 
+function getDeprecationReason(annotation) {
+  var tags = annotation.tags;
+  var idx, length, tag;
+
+  if (!tags) {
+    return null;
+  }
+
+  for (idx = 0, length = tags.length; idx < length; ++idx) {
+    tag = tags[idx];
+    if (tag.type === 'deprecated') {
+      return tag.string;
+    }
+  }
+
+  return null;
+}
+
 options.annotations.map(function(annotation) {
   var name = annotation.code.split(":")[0];
   var option = options.parsed[name];
 
   annotation.name = name.trim();
   annotation.category = getCategory(annotation);
+  annotation.deprecationReason = getDeprecationReason(annotation);
 
   return annotation;
 }).forEach(function(annotation) {
@@ -62,13 +84,26 @@ function table2html(annotations) {
 
   return header + annotations.map(function(annotation) {
     var name = annotation.name;
+    var description = '';
+
+    if (annotation.deprecationReason) {
+      description += "<div class='deprecation-msg'>" + deprecationMsg + " " +
+        // TODO: Remove this when the `dox` module is updated to also parse
+        //       annotations for Markdown.
+        // See:  "Parse tag strings with Markdown"
+        //       https://github.com/tj/dox/pull/139
+        marked(annotation.deprecationReason) +
+        "</div>";
+    }
+
+    description += annotation.description.full;
 
     return [
       "<tr>",
         "<td class='name' id='" + name + "'>",
           "<a href='#" + name + "'>" + name + "</a>",
         "</td>",
-        "<td class='desc'>" + annotation.description.full + "</td>",
+        "<td class='desc'>" + description + "</td>",
       "</tr>"
     ].join("\n");
   }).join("\n") + footer;

res/docs.css

@@ -49,3 +49,16 @@ a.anchor {
 .blog-list .link {
   padding-left: 20px;
 }
+
+.deprecation-msg {
+  margin-bottom: 1em;
+}
+
+.deprecation-msg strong {
+  font-weight: bold;
+}
+
+.deprecation-msg p {
+  display: inline;
+  margin: 0;
+}