Merge pull request #174 from jongyeol/feature/docservice-docstring-2-…

…view Add DocService's docString to html view
line · Jun 3, 2016 · d58e1f9 · d58e1f9
2 parents d6ed257 + c640d7b
commit d58e1f9
Show file tree

Hide file tree

Showing 4 changed files with 109 additions and 3 deletions.
diff --git a/src/main/resources/com/linecorp/armeria/server/docs/assets/css/armeria.css b/src/main/resources/com/linecorp/armeria/server/docs/assets/css/armeria.css
@@ -118,6 +118,11 @@ label {
   font-size: 60%;
 }
 
+.main div.description, .main td.description {
+  font-size: 100%;
+  text-align: justify;
+}
+
 .main td ul {
   list-style-type: none;
   padding-left: 0;
@@ -168,4 +173,4 @@ label {
 
 .debug-response {
   min-height: 256px;
-}
+}
diff --git a/src/main/resources/com/linecorp/armeria/server/docs/assets/js/armeria.js b/src/main/resources/com/linecorp/armeria/server/docs/assets/js/armeria.js
@@ -14,7 +14,7 @@ $(function () {
   var previousFragmentPath = null;
 
   $.getJSON('specification.json', function (data) {
-    specification = data;
+    specification = escapeDocString(updateDocString(data));
 
     renderNav();
     $(window).trigger('hashchange');
@@ -24,6 +24,85 @@ $(function () {
     render(URI(window.location.href));
   });
 
+  function parseParametersDocString(docString) {
+    var parameters = {};
+    if (docString != null) {
+      var pattern = /@param\s+(\w+)[\s\.]+(({@|[^@])*)(?=(@[\w]+|$|\s))/gm;
+      var match = pattern.exec(docString);
+      while (match != null) {
+        parameters[match[1]] = match[2];
+        match = pattern.exec(docString);
+      }
+    }
+    return parameters;
+  }
+
+  function removeParamDocString(docString) {
+    if (docString == null) {
+      return null;
+    }
+    return docString.replace(/@param .*[\n\r]*/mig, '');
+  }
+
+  function updateDocString(specification) {
+    // hierachy
+    // services.SERVICE_NAME.functions.FUNCTION_NAME.docString
+    // services.SERVICE_NAME.functions.FUNCTION_NAME.parameters[i].name (simple_string)
+    // services.SERVICE_NAME.functions.FUNCTION_NAME.parameters[i].docString
+    // classes.CLASS_NAME.docString
+    // classes.CLASS_NAME.fields[i].name (simple_name)
+    // classes.CLASS_NAME.fields[i].docString
+
+    var services = specification.services;
+    var classes = specification.classes;
+
+    for (var serviceName in services) {
+      var svc = services[serviceName];
+      for (var functionName in svc.functions) {
+        var func = svc.functions[functionName];
+        var childDocStrings = parseParametersDocString(func.docString);
+        func.docString = removeParamDocString(func.docString);
+        for (var idx in func.parameters) {
+          var param = func.parameters[idx];
+          if (param.name in childDocStrings) {
+            param.docString = childDocStrings[param.name];
+          }
+        }
+      }
+    }
+
+    for (var className in classes) {
+      var cls = classes[className];
+      var childDocStrings = parseParametersDocString(cls.docString);
+      cls.docString = removeParamDocString(cls.docString);
+      for (var idx in cls.fields) {
+        var field = cls.fields[idx];
+        if (field.name in childDocStrings) {
+          field.docString = childDocStrings[field.name];
+        }
+      }
+    }
+
+    return specification;
+  }
+
+  function escapeDocString(node) {
+    if (node instanceof Array) {
+      for (var idx in node) {
+        escapeDocString(node[idx]);
+      }
+    } else if (node instanceof Object) {
+      var docString = node['docString'];
+      if (docString && typeof docString === 'string') {
+        node['docString'] = escapeHtml(docString).replace(/\n/g, '<br>');
+      }
+      for (var key in node) {
+        escapeDocString(node[key]);
+      }
+    }
+    return node;
+  }
+
   function render(uri) {
     var fragmentUri = uri.fragment(true);
     var path = fragmentUri.pathname();
@@ -189,6 +268,20 @@ $(function () {
                  });
   }
 
+  function escapeHtml(string) {
+    var htmlEscapes = {
+      '&': '&amp;',
+      '<': '&lt;',
+      '>': '&gt;',
+      '"': '&quot;',
+      "'": '&#39;',
+      '/': '&#x2F;',
+      '`': '&#x60;',
+      '=': '&#x3D;'
+    };
+    return string.replace(/[&<>"'`=\/]/g, function(s) { return htmlEscapes[s]; });
+  }
+
   function escapeTag(value) {
     return value.replace(/</g, '&lt;').replace(/>/g, '&gt;');
   }

diff --git a/src/main/resources/com/linecorp/armeria/server/docs/index.html b/src/main/resources/com/linecorp/armeria/server/docs/index.html
@@ -80,6 +80,8 @@ <h1 class="page-header">Welcome to the Armeria documentation service</h1>
         <script id="function-template" type="text/x-handlebars-template">
           <h1 class="page-header"><code title="{{serviceName}}.{{function.name}}()">{{serviceSimpleName}}.{{function.name}}()</code></h1>
 
+          <div class="description">{{{function.docString}}}</div>
+
           <h2 class="sub-header">Parameters</h2>
           <div class="table-responsive">
             <table class="table table-striped table-condensed">
@@ -88,6 +90,7 @@ <h2 class="sub-header">Parameters</h2>
                 <th>Name</th>
                 <th>Required</th>
                 <th>Type</th>
+                <th>Description</th>
               </tr>
               </thead>
               <tbody>
@@ -96,6 +99,7 @@ <h2 class="sub-header">Parameters</h2>
                 <td><code>{{name}}</code></td>
                 <td>{{requirementType}}</td>
                 <td><code>{{{type.typeStr}}}</code></td>
+                <td class="description">{{{docString}}}</td>
               </tr>
               {{else}}
               <tr>
@@ -190,6 +194,8 @@ <h1 class="page-header" title="{{name}}">
             <code class="package-name">{{class.packageName}}</code>
           </h1>
 
+          <div class="description">{{{class.docString}}}</div>
+
           {{#if class.fields.length}}
           <h2 class="sub-header">Fields</h2>
           <div class="table-responsive">
@@ -199,6 +205,7 @@ <h2 class="sub-header">Fields</h2>
                 <th>Name</th>
                 <th>Required</th>
                 <th>Type</th>
+                <th>Description</th>
               </tr>
               </thead>
               <tbody>
@@ -207,6 +214,7 @@ <h2 class="sub-header">Fields</h2>
                 <td><code>{{name}}</code></td>
                 <td>{{requirementType}}</td>
                 <td><code>{{{type.typeStr}}}</code></td>
+                <td class="description">{{{docString}}}</td>
               </tr>
               {{/each}}
               </tbody>

diff --git a/src/test/resources/META-INF/armeria/thrift/cassandra.json b/src/test/resources/META-INF/armeria/thrift/cassandra.json
@@ -1545,7 +1545,7 @@
             "valueTypeId": "i32"
           },
           "oneway": false,
-          "doc": "Perform a get_count in parallel on the given list<binary> keys. The return value maps keys to the count found.\n",
+          "doc": "Perform a get_count in parallel on the given list<binary> keys. The return value maps keys to the count found.\n@param keys. this is test doc string.",
           "arguments": [
             {
               "key": 1,