chore(website): Fix parsing of summaries in function list and return descriptions

Closing #2486 and #2672

Author: sjelin

Diff for: website/js/api-controller.js

@@ -62,25 +62,8 @@
       $anchorScroll();
     };
 
-    /**
-     * Use the $sce service to trust the html rendered in the view.
-     * @param html
-     */
     $scope.trust = function(html) {
-      if (!html) {
-        return;
-      }
-
-      // Does it come with a type? Types come escaped as [description](theType).
-      var match;
-      while (match = html.match(/(\[(.*?)\]\((.*?)\))/)) {
-        var link = '<a href="' +
-            (match[3].match(/^https?:\/\//) ? '' : '#/api?view=') + match[3] +
-            '">' + match[2] + '</a>';
-        html = html.replace(match[1], link);
-      }
-
-      return $sce.trustAsHtml(html);
+      return trustHTML($sce, html);
     };
   };
 
@@ -153,8 +136,25 @@
 
       // Add short description.
       if (item.description) {
-        item.shortDescription =
-            item.description.substring(0., item.description.indexOf('.') + 1);
+        // Find the correct portion of the description
+        
+        // The following parsing is OK most of the time
+        var sentenceEnd = item.description.search(/\.\s|\.$/) + 1 || Infinity;
+        var paragraphEnd = item.description.indexOf('</p>') + 4;
+        if (paragraphEnd == 3) {
+          paragraphEnd = Infinity
+        }
+        var shortDescription = item.description.substring(0, Math.min(
+            item.description.length, sentenceEnd, paragraphEnd)).trim();
+
+        // Remove <p> tags
+        if (shortDescription.substr(0,3) == '<p>') {
+          shortDescription = shortDescription.substr(3);
+          if (shortDescription.substr(-4) == '</p>') {
+            shortDescription = shortDescription.substr(0, shortDescription.length - 4);
+          }
+        }
+        item.shortDescription = shortDescription;
       }
     });
 
@@ -201,7 +201,6 @@
 
     var addItemToList = function(item, depth) {
       if (item.inList) {
-        console.log(item.name);
         return;
       }
       item.treeClasses = 'depth-' + depth;
@@ -217,7 +216,6 @@
         });
       }
       if (item.extends) {
-        console.log(item.base.name);
         var parent = self.itemsByName[item.base.name];
         if (parent != null) {
           addItemToList(parent, depth + 1);

Diff for: website/js/directives.js

@@ -56,6 +56,11 @@
       scope: {
         list: '=ptorFunctionList'
       },
+      controller: function($scope, $sce) {
+        $scope.trust = function(html) {
+          return trustHTML($sce, html);
+        };
+      },
       templateUrl: 'partials/ptor-function-list.html'
     };
   });

Diff for: website/js/shared.js

@@ -0,0 +1,25 @@
+/*
+ * Use the $sce service to trust the html rendered in the view.
+ * Also parse links
+ *
+ * @param $sce The $sce service from Angular
+ * @param {String} html The HTML to trust
+ * @return {*} An object that can be passed to $sce.getTrustedHtml(value) to
+ *   obtain the original value
+ */
+function trustHTML($sce, html) {
+  if (!html) {
+    return;
+  }
+
+  // Does it come with a type? Types come escaped as [description](theType).
+  var match;
+  while (match = html.match(/(\[(.*?)\]\((.*?)\))/)) {
+    var link = '<a href="' +
+        (match[3].match(/^https?:\/\//) ? '' : '#/api?view=') + match[3] +
+        '">' + match[2] + '</a>';
+    html = html.replace(match[1], link);
+  }
+
+  return $sce.trustAsHtml(html);
+}

Diff for: website/partials/api.html

@@ -149,7 +149,7 @@ <h4>Returns</h4>
             <tbody>
             <tr>
               <td ng-bind-html="trust(currentItem.returnString)"></td>
-              <td>{{currentItem.returns.description}}</td>
+              <td ng-bind-html="trust(currentItem.returns.description)"></td>
             </tr>
             </tbody>
           </table>

Diff for: website/partials/ptor-function-list.html

@@ -14,7 +14,7 @@
             ng-bind="item.displayName">
         </a>
       </td>
-      <td ng-bind="item.shortDescription"></td>
+      <td ng-bind-html="trust(item.shortDescription)"></td>
     </tr>
     </tbody>
   </table>

Diff for: website/test/unit/api-controller-spec.js

@@ -1,15 +1,16 @@
 'use strict';
 
 describe('ApiCtrl', function() {
-  var $controller_, $httpBackend, $location, $rootScope_, ctrl, scope;
+  var $controller_, $httpBackend, $location, $sce, $rootScope_, ctrl, scope;
 
   beforeEach(module('protractorApp'));
 
   beforeEach(inject(
-      function($controller, $rootScope, _$httpBackend_, _$location_) {
+      function($controller, $rootScope, _$httpBackend_, _$location_, _$sce_) {
         $controller_ = $controller;
         $httpBackend = _$httpBackend_;
         $location = _$location_;
+        $sce = _$sce_;
         $rootScope_ = $rootScope;
       }));
 
@@ -205,4 +206,19 @@ describe('ApiCtrl', function() {
       expect(item.base.items.length).toBe(1);
     });
   });
+
+  describe('trustHTML', function() {
+    it('should reject falsy html', function() {
+      expect(trustHTML($sce, false)).toBe(undefined);
+    });
+
+    it('should run truster', function() {
+      expect($sce.getTrustedHtml(trustHTML($sce, 'html'))).toBe('html');
+    });
+
+    it('should expand links', function() {
+      expect($sce.getTrustedHtml(trustHTML($sce, '[description](type)'))).toBe(
+          '<a href="#/api?view=type">description</a>');
+    });
+  });
 });