Properly escape angle brackets and find their corresponding links in docgen.

pkg/docgen/lib/docgen.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /// **docgen** is a tool for creating machine readable representations of Dart
 /// code metadata, including: classes, members, comments and annotations.
 ///
 /// docgen is run on a `.dart` file or a directory containing `.dart` files.
 ///
 ///      $ dart docgen.dart [OPTIONS] [FILE/DIR]
@@ skipping 491 matching lines @@
   if (mdnType['summary'] == null || mdnType['summary'] == "") return '';
   if (mdnType['srcUrl'] == null) return '';
   return _htmlMdn(mdnType['summary'], mdnType['srcUrl']);
 }
 
 String _htmlMdn(String content, String url) {
   return '<div class="mdn">' + content.trim() + '<p class="mdn-note">'
       '<a href="' + url.trim() + '">from Mdn</a></p></div>';
 }
 
+/// Look for the specified name starting with the current member, and
+/// progressively working outward to the current library scope.
+String findElementInScope(String name, LibraryMirror currentLibrary,
+    ClassMirror currentClass, MemberMirror currentMember) {
+  var memberScope = currentMember == null ?
+      null : currentMember.lookupInScope(name);
+  if (memberScope != null) {
+    return docName(memberScope);
+  } else {
+    var classScope = currentClass == null ?
+        null : currentClass.lookupInScope(name);
+    if (classScope != null) {
+      return docName(classScope);
+    } else {
+      var libraryScope = currentLibrary == null ?
+          null : currentLibrary.lookupInScope(name);
+      if (libraryScope != null) {
+        return docName(libraryScope);
+      }
+    }
+  }
+  return null;
+}
+
+/// This is a more complex reference. Try to break up if its of the form A<B>
+/// where A is an alphanumeric string and B is an A, a list of B ("B, B, B"),
+/// or of the form A<B>. Note: unlike other the other markdown-style links, all
+/// text inside the square brackets is treated as part of the link (aka the * is
+/// interpreted literally as a *, not as a indicator for bold <em>.
+markdown.Node fixComplexReference(String name, LibraryMirror currentLibrary,
+    ClassMirror currentClass, MemberMirror currentMember) {
+  var LESS_THAN = '&lt;';
+  var childrenElements = [];
+  var curName = name;
+  var alphanumeric = new RegExp('[a-zA-Z0-9]');

[Alan Knight, 2013/11/06 21:19:04]

Should this also allow _ as legal in names?

Also, library names can have dots in them. So will this handle

[stuff.stuff_handlers.Stuff<stuff.stuff_handlers.OtherStuff>]  ?

+  // Parse into multiple elements we can try to resolve.
+  do {
+    var index = curName.indexOf(LESS_THAN);
+    if (index != -1) {
+      var substring = curName.substring(0, index);
+      curName = curName.substring(index + LESS_THAN.length);

[Alan Knight, 2013/11/06 21:19:04]

This whole section is pretty hard to follow. Can it be either re-organized to be
easier to follow or put in some more comments as to what's going on.

+      String elementName = findElementInScope(substring, currentLibrary,
+          currentClass, currentMember);
+      if (elementName != null) {
+        childrenElements.add(new markdown.Element.text('a', elementName));
+      } else {
+        childrenElements.add(new markdown.Text(elementName));
+      }
+      childrenElements.add(new markdown.Text('<'));
+      if (alphaNumeric.hasMatch(curName[0])) {
+        childrenElements.add(new markdown.Text(curName[0]));
+        curName = curName.substring(1);
+      }
+    } else {
+      childrenElements.add(new markdown.Text(curName));
+      curName = '';
+    }
+  } while(curName.length > 0);
+
+  // Produce an html representation of our parsed and resolved (when possible)
+  // elements. Group unresolved (text) elements into "link" elements so they
+  // display as code.
+  var accumulatedHtml = '';
+  var accumulatedText = '';
+  while (childrenElements.length  > 0) {

[Alan Knight, 2013/11/06 21:19:04]

Couldn't this be written as a loop over childrenElements? It doesn't seem like
we modify it in the middle or use the result once we're done.

+    var child = childrenElements.removeAt(0);
+
+    if (child is markdown.Text) {
+      accumulatedText = '${accumulatedText}${child.text}';
+    } else if (child is markdown.Element) {
+      var nodeList = [];
+      if (accumulatedText != '') {
+        nodeList.add(new markdown.Element.text('a', accumulatedText));
+        accumulatedText = '';
+      }
+      nodeList.add(child);
+      accumulatedHtml += markdown.renderToHtml(nodeList);
+    }
+  }
+  if (accumulatedText != '') {
+    accumulatedHtml += markdown.renderToHtml([
+        new markdown.Element.text('a', accumulatedText)]);
+  }
+  return new markdown.Text(accumulatedHtml);
+}
+
 /// Converts all [foo] references in comments to <a>libraryName.foo</a>.
 markdown.Node fixReference(String name, LibraryMirror currentLibrary,
     ClassMirror currentClass, MemberMirror currentMember) {
-  var reference;
-  var memberScope = currentMember == null ?
-      null : currentMember.lookupInScope(name);
-  if (memberScope != null) {
-    reference = docName(memberScope);
-  } else {
-    var classScope = currentClass == null ?
-        null : currentClass.lookupInScope(name);
-    if (classScope != null) {
-      reference = docName(classScope);
-    } else {
-      var libraryScope = currentLibrary == null ?
-          null : currentLibrary.lookupInScope(name);
-      reference = libraryScope != null ? docName(libraryScope) : name;
-    }
+  // Attempt the look up the whole name up in the scope.
+  String elementName =
+      findElementInScope(name, currentLibrary, currentClass, currentMember);
+  if (elementName != null) {
+    return new markdown.Element.text('a', elementName);
   }
-  return new markdown.Element.text('a', reference);
+  return fixComplexReference(name, currentLibrary, currentClass, currentMember);
 }
 
 /// Returns a map of [Variable] objects constructed from [mirrorMap].
 Map<String, Variable> _variables(Map<String, VariableMirror> mirrorMap) {
   var data = {};
   // TODO(janicejl): When map to map feature is created, replace the below with
   // a filter. Issue(#9590).
   mirrorMap.forEach((String mirrorName, VariableMirror mirror) {
     _currentMember = mirror;
     if (_includePrivate || !_isHidden(mirror)) {
@@ skipping 696 matching lines @@
 String docName(DeclarationMirror m) {
   if (m is LibraryMirror) {
     return (m as LibraryMirror).qualifiedName.replaceAll('.','-');
   }
   var owner = m.owner;
   if (owner == null) return m.qualifiedName;
   // For the unnamed constructor we just return the class name.
   if (m.simpleName == '') return docName(owner);
   return docName(owner) + '.' + m.simpleName;
 }