From 0a99d0f211142774471983e8693dc68cfb26b83a Mon Sep 17 00:00:00 2001
From: Marc Jansen <jansen@terrestris.de>
Date: Thu, 3 Sep 2015 16:32:46 +0200
Subject: [PATCH] Automatically mark required options in API-docs

---
 config/jsdoc/api/plugins/typedefs.js | 64 ++++++++++++++++++++++++++++
 1 file changed, 64 insertions(+)

diff --git a/config/jsdoc/api/plugins/typedefs.js b/config/jsdoc/api/plugins/typedefs.js
index 1b4543d1b5..8d12e424b0 100644
--- a/config/jsdoc/api/plugins/typedefs.js
+++ b/config/jsdoc/api/plugins/typedefs.js
@@ -5,6 +5,10 @@
 
 var lastOlxTypedef = null;
 var olxTypes = {};
+// names of the olx typenames
+var olxTypeNames = [];
+// types that are undefined or typedefs containing undefined
+var undefinedLikes = null;
 
 function addSubparams(params) {
   for (var j = 0, jj = params.length; j < jj; ++j) {
@@ -23,6 +27,63 @@ function addSubparams(params) {
   }
 }
 
+/**
+ * Changes the description of the param, if it is found to be a required
+ * option of an olxTypeName.
+ */
+function markRequiredIfNeeded(doclet){
+  var memberof = doclet.memberof;
+  // only check doclets that belong to an olxTypeName
+  if (!memberof || olxTypeNames.indexOf(memberof) == -1) {
+    return doclet;
+  }
+
+  var types = doclet.type.names;
+  var isRequiredParam = true;
+
+  // iterate over all types that are like-undefined (see above for explanation)
+  for (var idx = undefinedLikes.length - 1; idx >= 0; idx--) {
+    var undefinedLike = undefinedLikes[idx];
+    // … if the current types contains a type that is undefined-like,
+    // it is not required.
+    if (types.indexOf(undefinedLike) != -1) {
+      isRequiredParam = false;
+    }
+  }
+
+  if (isRequiredParam) {
+    var reqSnippet = '<span class="required-option">Required.</span></p>';
+    var endsWithP = /<\/p>$/i;
+    var description = doclet.description;
+    if (description && endsWithP.test(description)) {
+      description = description.replace(endsWithP, ' ' + reqSnippet);
+    } else if (doclet.description === undefined) {
+      description = '<p>' + reqSnippet;
+    }
+    doclet.description = description;
+  }
+  return doclet;
+}
+
+/**
+ * Iterates over all doclets and finds the names of types that contain
+ * undefined. Stores the names in the global variable undefinedLikes, so
+ * that e.g. markRequiredIfNeeded can use these.
+ */
+function findTypesLikeUndefined(doclets) {
+  undefinedLikes = ['undefined']; // include type 'undefined' explicitly
+  for (var i = doclets.length - 1; i >= 0; --i) {
+    var doclet = doclets[i];
+    if(doclet.kind === 'typedef') {
+      var types = doclet.type.names;
+      if (types.indexOf('undefined') !== -1) {
+        // the typedef contains 'undefined', so it self is undefinedLike.
+        undefinedLikes.push(doclet.longname);
+      }
+    }
+  }
+}
+
 exports.handlers = {
 
   newDoclet: function(e) {
@@ -34,6 +95,7 @@ exports.handlers = {
       }
       if (doclet.kind == 'typedef') {
         lastOlxTypedef = doclet;
+        olxTypeNames.push(doclet.longname);
         olxTypes[doclet.longname] = [];
         doclet.properties = [];
       } else if (lastOlxTypedef && doclet.memberof == lastOlxTypedef.longname) {
@@ -51,12 +113,14 @@ exports.handlers = {
 
   parseComplete: function(e) {
     var doclets = e.doclets;
+    findTypesLikeUndefined(doclets);
     for (var i = doclets.length - 1; i >= 0; --i) {
       var doclet = doclets[i];
       var params = doclet.params;
       if (params) {
         addSubparams(params);
       }
+      markRequiredIfNeeded(doclet);
     }
   }