Merge pull request #62 from Zemke/links

Enhanced support for JSDoc link references and custom types
allenhwkim · Mar 27, 2016 · 5af3d10 · 5af3d10
2 parents 0551a99 + 7f29b5f
commit 5af3d10
Show file tree

Hide file tree

Showing 2 changed files with 134 additions and 22 deletions.
diff --git a/angular-template/html/class.html b/angular-template/html/class.html
@@ -2,7 +2,7 @@
       <dt></dt>
       <dd>
         <div ht-if="description" class="description">
-          {{ description.replace(/\{@link (.*)\}/, '<a href="$1.html">$1</a>') }}
+          {{ description.replace(/\{@link (.*?)(#.*?)?\}/g, '<a href="$1.html$2">$1$2</a>') }}
         </div>
         <div class="details"></div>
         <div ht-if="newScope">
@@ -35,11 +35,18 @@ <h5>Dependencies:</h5>
             </thead>
             <tbody>
               <tr ht-repeat="param in params">
-                <td class="name" nowrap>{{ param.name }}</td>
+                <td class="name" nowrap>
+                  <a id="{{ param.name }}"></a>
+                  {{ param.name }}
+                </td>
                 <td class="type"><span class="param-type">
-                  {{ param.type && param.type.names.join(" | ") }}
+                  {{ param.typeDefinitionUrl }}
                 </span></td>
-                <td class="description last">{{ param.description }}</td>
+                <td class="description last">
+                  <span ht-if="param.description">
+                    {{ param.description.replace(/\{@link (.*?)(#.*?)?\}/g, '<a href="$1.html$2">$1$2</a>') }}
+                  </span>
+                </td>
               </tr>
             </tbody>
           </table>
@@ -53,10 +60,16 @@ <h5>Properties:</h5>
             <tbody>
               <tr ht-repeat="prop in properties">
                 <td class="name" nowrap>{{ prop.name }}</td>
-                <td class="type"><span class="param-type">
-                  {{ prop.type && prop.type.names.join(" | ") }}
-                </span></td>
-                <td class="description last">{{ prop.description }}</td>
+                <td class="type">
+                  <span class="param-type">
+                    {{ prop.typeDefinitionUrl }}
+                  </span>
+                </td>
+                <td class="description last">
+                  <span ht-if="prop.description">
+                    {{ prop.description.replace(/\{@link (.*?)(#.*?)?\}/g, '<a href="$1.html$2">$1$2</a>') }}
+                  </span>
+                </td>
               </tr>
             </tbody>
           </table>
@@ -71,9 +84,13 @@ <h5>Attributes:</h5>
               <tr ht-repeat="attr in attributes">
                 <td class="name" nowrap>{{ attr.name }}</td>
                 <td class="type"><span class="param-type">
-                  {{ attr.type && attr.type.names.join(" | ") }}
+                  {{ attr.typeDefinitionUrl }}
                 </span></td>
-                <td class="description last">{{ marked(attr.description||'') }}</td>
+                <td class="description last">
+                  <span ht-if="attr.description">
+                    {{ marked(attr.description.replace(/\{@link (.*?)(#.*?)?\}/g, '<a href="$1.html$2">$1$2</a>')||'') }}
+                  </span>
+                </td>
               </tr>
             </tbody>
           </table>
@@ -130,19 +147,21 @@ <h3 class="subsection-title">Members</h3>
         <h3 class="subsection-title">Methods</h3>
         <dl ht-repeat="func in children.function">
           <dt>
-            <a href="{{ func.sourceUrl }}" class="name-link">
+            <a href="{{ func.sourceUrl }}" class="name-link" id="{{ func.name }}">
               <h4 class="name">
                 {{ func.name }}
                 <span ht-if="func.params" class="signature">({{ func.params.map(function(param){return param.name;}).join(", ") }})</span>
-                <span ht-if="func.returns && func.returns[0].type" class="type-signature">
-                  -&gt; {{ func.returns[0].type.names.join(" | ") }}
+                <span ht-if="func.returns[0].typeDefinition" class="type-signature">
+                  -&gt; {{ func.returns[0].typeDefinition }}
                 </span>
               </h4>
             </a>
           </dt>
           <dd>
             <div class="description">
-              {{ func.description }}
+              <span ht-if="func.description">
+                {{ func.description.replace(/\{@link (.*?)(#.*?)?\}/g, '<a href="$1.html$2">$1$2</a>') }}
+              </span>
             </div>
             <div ht-if="func.examples && func.examples.length">
               <h5>Example</h5>
@@ -158,9 +177,13 @@ <h5>Parameters:</h5>
                   <tr ht-repeat="param in func.params">
                     <td class="name">{{ param.name }}</td>
                     <td class="type"><span class="param-type">
-                      {{ param.type && param.type.names.join(" | ").replace(new RegExp( String.fromCharCode(60), "g" ), "&lt;") }}
+                      {{ param.typeDefinitionUrl }}
                     </span></td>
-                    <td class="description last">{{ param.description }}</td>
+                    <td class="description last">
+                      <span ht-if="param.description">
+                        {{ param.description.replace(/\{@link (.*?)(#.*?)?\}/g, '<a href="$1.html$2">$1$2</a>') }}
+                      </span>
+                    </td>
                   </tr>
                 </tbody>
               </table>
@@ -173,10 +196,16 @@ <h5>Returns:</h5>
                 </thead>
                 <tbody>
                   <tr ht-repeat="ret in func.returns">
-                    <td class="type"><span class="param-type">
-                      {{ ret.type && ret.type.names.join(" | ").replace(new RegExp( String.fromCharCode(60), "g" ), "&lt;") }}
-                    </span></td>
-                    <td class="description last">{{ ret.description }}</td>
+                    <td class="type">
+                      <span class="param-type">
+                        {{ ret.typeDefinitionUrl }}
+                      </span>
+                    </td>
+                    <td class="description last">
+                      <span ht-if="ret.description">
+                        {{ ret.description.replace(/\{@link (.*?)(#.*?)?\}/g, '<a href="$1.html$2">$1$2</a>') }}
+                      </span>
+                    </td>
                   </tr>
                 </tbody>
               </table>

diff --git a/common/plugins/ngdoc.js b/common/plugins/ngdoc.js
@@ -16,12 +16,43 @@ exports.defineTags = function(dictionary) {
     canHaveType: true,
     canHaveName: true,
     onTagged: function(doclet, tag) {
-      if (!doclet.attributes) { doclet.attributes = []; }
-      doclet.attributes.push(tag.value);
+      doclet.attributes = parseParamTypes(doclet.attributes, tag);
     }
   })
   .synonym('attr');
 
+  dictionary.defineTag('param', {
+    mustHaveValue: true,
+    canHaveType: true,
+    canHaveName: true,
+    onTagged: function(doclet, tag) {
+      doclet.params = parseParamTypes(doclet.params, tag);
+    }
+  });
+
+  dictionary.defineTag('property', {
+    mustHaveValue: true,
+    canHaveType: true,
+    canHaveName: true,
+    onTagged: function(doclet, tag) {
+      doclet.properties = parseParamTypes(doclet.properties, tag);
+    }
+  });
+
+  dictionary.defineTag('returns', {
+    mustHaveValue: false,
+    canHaveType: true,
+    canHaveName: false,
+    onTagged: function(doclet, tag) {
+      var returnsText = new RegExp(/@returns (\{.*\}.*)/).exec(doclet.comment);
+
+      if (returnsText) {
+        tag.text = returnsText[1];
+        doclet.returns = parseParamTypes(doclet.returns, tag);
+      }
+    }
+  });
+
   dictionary.defineTag('restrict', {
     mustHaveValue: true,
     onTagged: function(doclet, tag) {
@@ -78,3 +109,55 @@ exports.defineTags = function(dictionary) {
     }
   });
 };
+
+function parseParamTypes(docletParams, tag) {
+  if (!docletParams) {
+    docletParams = [];
+  }
+
+  var result = {
+    name: tag.value.name,
+    description: tag.value.description
+  };
+
+  var defaultTypes = ['boolean', 'string', 'expression', '*', 'mixed', 'number', 'null', 'undefined', 'function',
+    '{}', 'object', '[]', 'array', 'void'];
+  var defaultTypeStarts = ['\'', '"', '[', '{'];
+
+  var typeDoc = new RegExp(/\{(.*?)\}/).exec(tag.text);
+
+  if (!typeDoc) {
+    result.typeDefinition =  '*';
+    docletParams.push(result);
+    return;
+  }
+
+  var types = typeDoc[1].split('|');
+  var typeRegex = new RegExp(/(.*?)(\[\])?$/);
+
+  var parseTypeDefinitionUrl = '';
+  var parseTypeDefinition = '';
+  var i = 0;
+  for (; i < types.length; i++) {
+    var type = typeRegex.exec(types[i]);
+
+    if (i > 0) {
+      parseTypeDefinitionUrl += '|';
+      parseTypeDefinition += '|';
+    }
+
+    if (defaultTypes.indexOf(type[1].toLowerCase()) !== -1 || defaultTypeStarts.indexOf(type[1][0]) !== -1) {
+      parseTypeDefinitionUrl += type[1] + (type[2] || '');
+    } else {
+      parseTypeDefinitionUrl += '<a href="' + type[1] + '.html">' + type[1] + (type[2] || '') + '</a>';
+    }
+
+    parseTypeDefinition += type[1] + (type[2] || '');
+  }
+
+  result.typeDefinitionUrl = parseTypeDefinitionUrl;
+  result.typeDefinition = parseTypeDefinition;
+  docletParams.push(result);
+
+  return docletParams;
+}