From b386283391bec67a7ade6cc826fa35744e64a2e8 Mon Sep 17 00:00:00 2001
From: Anton Astashov <anton.astashov@gmail.com>
Date: Sat, 17 Dec 2016 15:48:12 -0600
Subject: [PATCH 1/3] Resolve non-imported symbols in comments [#1153]
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

@Hixie noticed, that sometimes, a library, like the Flutter rendering
library, wants to refer to another library, like the Flutter widgets
library, in the documentation, but doesn't want to introduce a
dependency in the code. Currently, there’s no mechanisms in dartdoc,
which allows that.

This commit adds that. You can use either a short name (e.g. [icon]) or
a fully qualified name (like, [material.Icon.icon]), in the HTML docs,
it always will be shown as a short name though (is that a desired
behavior?).  Dartdoc will go over all the libraries, classes, methods,
properties, constants of the package that is being documented, and will
try to resolve the symbol. If it’s successful, it will add the link to
it, same way as when the symbol is in scope.

Some outstanding questions:

* What to do in case of ambiguity here? Show a warning, crash with an
  error message, ignore?
* Do we want to show short name in case a fully qualified name is
  provided? I saw in the comments in the ticket
  (https://github.com/dart-lang/dartdoc/issues/1153#issuecomment-236012803)
  that @Hixie would want that.
* Anything else?

Testing: Unit tests, of course, also tried to generate Flutter docs with
that, and observed that the links for previously non-resolved symbols
work.
---
 lib/src/markdown_processor.dart               | 74 ++++++++++++++++---
 test/model_test.dart                          |  4 +-
 testing/test_package/lib/src/extending.dart   |  2 +-
 .../test_package_docs/ex/ShapeType-class.html |  4 +-
 .../BaseForDocComments/doAwesomeStuff.html    |  2 +-
 .../two_exports/ExtendingClass-class.html     |  2 +-
 6 files changed, 69 insertions(+), 19 deletions(-)

diff --git a/lib/src/markdown_processor.dart b/lib/src/markdown_processor.dart
index 5a83a70f16..0276add8c3 100644
--- a/lib/src/markdown_processor.dart
+++ b/lib/src/markdown_processor.dart
@@ -28,6 +28,12 @@ const List<String> _oneLinerSkipTags = const ["code", "pre"];
 
 final List<md.InlineSyntax> _markdown_syntaxes = [new _InlineCodeSyntax()];
 
+class MatchingLinkResult {
+  final ModelElement element;
+  final String label;
+  MatchingLinkResult(this.element, this.label);
+}
+
 // TODO: this is in the wrong place
 NodeList<CommentReference> _getCommentRefs(ModelElement modelElement) {
   if (modelElement == null) return null;
@@ -67,10 +73,10 @@ NodeList<CommentReference> _getCommentRefs(ModelElement modelElement) {
 }
 
 /// Returns null if element is a parameter.
-ModelElement _getMatchingLinkElement(
+MatchingLinkResult _getMatchingLinkElement(
     String codeRef, ModelElement element, List<CommentReference> commentRefs,
     {bool isConstructor: false}) {
-  if (commentRefs == null) return null;
+  if (commentRefs == null) return new MatchingLinkResult(null, null);
 
   Element refElement;
   bool isEnum = false;
@@ -87,7 +93,9 @@ ModelElement _getMatchingLinkElement(
   }
 
   // Did not find an element in scope
-  if (refElement == null) return null;
+  if (refElement == null) {
+    return _findRefElementInLibrary(codeRef, element, commentRefs);
+  }
 
   if (refElement is PropertyAccessorElement) {
     // yay we found an accessor that wraps a const, but we really
@@ -99,7 +107,7 @@ ModelElement _getMatchingLinkElement(
     }
   }
 
-  if (refElement is ParameterElement) return null;
+  if (refElement is ParameterElement) return new MatchingLinkResult(null, null);
 
   // bug! this can fail to find the right library name if the element's name
   // we're looking for is the same as a name that comes in from an imported
@@ -114,24 +122,66 @@ ModelElement _getMatchingLinkElement(
     // Is there a way to pull this from a registry of known elements?
     // Seems like we're creating too many objects this way.
     if (isEnum) {
-      return new EnumField(refElement, refLibrary);
+      return new MatchingLinkResult(new EnumField(refElement, refLibrary), null);
     }
-    return new ModelElement.from(refElement, refLibrary);
+    return new MatchingLinkResult(new ModelElement.from(refElement, refLibrary), null);
+  }
+  return new MatchingLinkResult(null, null);
+}
+
+MatchingLinkResult _findRefElementInLibrary(String codeRef, ModelElement element, List<CommentReference> commentRefs) {
+  final package = element.library.package;
+  final Map<String, ModelElement> result = {};
+  package.libraries.forEach((library) {
+    final List<ModelElement> modelElements = []
+      ..addAll(library.allClasses)
+      ..addAll(library.constants)
+      ..addAll(library.enums)
+      ..addAll(library.functions)
+      ..addAll(library.properties)
+      ..addAll(library.typedefs);
+
+    library.allClasses.forEach((c) {
+      modelElements.addAll(c.allInstanceMethods);
+      modelElements.addAll(c.allInstanceProperties);
+      modelElements.addAll(c.allOperators);
+      modelElements.addAll(c.staticMethods);
+      modelElements.addAll(c.staticProperties);
+    });
+
+    modelElements.forEach((modelElement) {
+      if (codeRef == modelElement.name || codeRef == modelElement.fullyQualifiedName) {
+        result[modelElement.fullyQualifiedName] = modelElement;
+      }
+    });
+  });
+
+  if (result.isEmpty) {
+    return new MatchingLinkResult(null, null);
+  } else if (result.length == 1) {
+    return new MatchingLinkResult(result.values.first, result.values.first.name);
+  } else {
+    if (_emitWarning) {
+      print("Abiguous reference '${codeRef}' in '${element.fullyQualifiedName}', " +
+        "we found it in the following elements: ${result.keys.map((k) => "'${k}'").join(", ")}");
+    }
+    return new MatchingLinkResult(null, null);
   }
-  return null;
 }
 
 String _linkDocReference(String reference, ModelElement element,
     NodeList<CommentReference> commentRefs) {
-  ModelElement linkedElement;
   // support for [new Constructor] and [new Class.namedCtr]
   var refs = reference.split(' ');
+  MatchingLinkResult result;
   if (refs.length == 2 && refs.first == 'new') {
-    linkedElement = _getMatchingLinkElement(refs[1], element, commentRefs,
+    result = _getMatchingLinkElement(refs[1], element, commentRefs,
         isConstructor: true);
   } else {
-    linkedElement = _getMatchingLinkElement(reference, element, commentRefs);
+    result = _getMatchingLinkElement(reference, element, commentRefs);
   }
+  final linkedElement = result.element;
+  final label = result.label ?? reference;
   if (linkedElement != null) {
     var classContent = '';
     if (linkedElement.isDeprecated) {
@@ -139,12 +189,12 @@ String _linkDocReference(String reference, ModelElement element,
     }
     // this would be linkedElement.linkedName, but link bodies are slightly
     // different for doc references. sigh.
-    return '<a ${classContent}href="${linkedElement.href}">$reference</a>';
+    return '<a ${classContent}href="${linkedElement.href}">$label</a>';
   } else {
     if (_emitWarning) {
       print("  warning: unresolved doc reference '$reference' (in $element)");
     }
-    return '<code>${HTML_ESCAPE.convert(reference)}</code>';
+    return '<code>${HTML_ESCAPE.convert(label)}</code>';
   }
 }
 
diff --git a/test/model_test.dart b/test/model_test.dart
index 627b25f82e..a4547418d2 100644
--- a/test/model_test.dart
+++ b/test/model_test.dart
@@ -276,7 +276,7 @@ void main() {
       test(
           'link to a name in another library in this package, but is not imported into this library, is codeified',
           () {
-        expect(docsAsHtml, contains('<code>doesStuff</code>'));
+        expect(docsAsHtml, contains('<a href="anonymous_library/doesStuff.html">doesStuff</a>'));
       });
 
       test(
@@ -427,7 +427,7 @@ void main() {
       expect(resolved, isNotNull);
       expect(resolved,
           contains('<a href="two_exports/BaseClass-class.html">BaseClass</a>'));
-      expect(resolved, contains('linking over to <code>Apple</code>.'));
+      expect(resolved, contains('linking over to <a href="ex/Apple-class.html">Apple</a>.'));
     });
 
     test('references to class and constructors', () {
diff --git a/testing/test_package/lib/src/extending.dart b/testing/test_package/lib/src/extending.dart
index c60eb1d95f..fae34934b3 100644
--- a/testing/test_package/lib/src/extending.dart
+++ b/testing/test_package/lib/src/extending.dart
@@ -8,5 +8,5 @@ int topLevelVariable = 1;
 ///
 /// Also check out [topLevelVariable].
 ///
-/// This should not work: linking over to [Apple].
+/// This also should work: linking over to [Apple].
 class ExtendingClass extends BaseClass {}
diff --git a/testing/test_package_docs/ex/ShapeType-class.html b/testing/test_package_docs/ex/ShapeType-class.html
index 25e49eba0c..1714eac4a7 100644
--- a/testing/test_package_docs/ex/ShapeType-class.html
+++ b/testing/test_package_docs/ex/ShapeType-class.html
@@ -136,8 +136,8 @@ <h5><a href="ex/ex-library.html">ex</a></h5>
 
     <section class="desc markdown">
       <p>Foo bar.</p><ol start="3"><li>All references should be hyperlinks. <a href="ex/MyError-class.html">MyError</a> and
-<code>ShapeType</code> and <a href="ex/MyError-class.html">MyError</a> and <code>MyException</code> and
-<a href="ex/MyError-class.html">MyError</a> and <code>MyException</code> and
+<a href="ex/ShapeType-class.html">ShapeType</a> and <a href="ex/MyError-class.html">MyError</a> and <a href="ex/MyException-class.html">MyException</a> and
+<a href="ex/MyError-class.html">MyError</a> and <a href="ex/MyException-class.html">MyException</a> and
 <code>List&lt;int&gt;</code> foo bar.</li></ol>
     </section>
     
diff --git a/testing/test_package_docs/fake/BaseForDocComments/doAwesomeStuff.html b/testing/test_package_docs/fake/BaseForDocComments/doAwesomeStuff.html
index d090335382..8e579efa69 100644
--- a/testing/test_package_docs/fake/BaseForDocComments/doAwesomeStuff.html
+++ b/testing/test_package_docs/fake/BaseForDocComments/doAwesomeStuff.html
@@ -117,7 +117,7 @@ <h5><a href="fake/BaseForDocComments-class.html">BaseForDocComments</a></h5>
 <p>Reference to a top-level const in another library <a href="ex/incorrectDocReferenceFromEx-constant.html">incorrectDocReferenceFromEx</a></p>
 <p>Reference to prefixed-name from another lib <a href="css/theOnlyThingInTheLibrary.html">css.theOnlyThingInTheLibrary</a> xx</p>
 <p>Reference to a name that exists in this package, but is not imported
-in this library <code>doesStuff</code> xx</p>
+in this library <a href="anonymous_library/doesStuff.html">doesStuff</a> xx</p>
 <p>Reference to a name of a class from an import of a library that exported
 the name <a href="two_exports/BaseClass-class.html">BaseClass</a> xx</p>
     </section>
diff --git a/testing/test_package_docs/two_exports/ExtendingClass-class.html b/testing/test_package_docs/two_exports/ExtendingClass-class.html
index 7ac640892a..f7f4c382fc 100644
--- a/testing/test_package_docs/two_exports/ExtendingClass-class.html
+++ b/testing/test_package_docs/two_exports/ExtendingClass-class.html
@@ -95,7 +95,7 @@ <h5><a href="two_exports/two_exports-library.html">two_exports</a></h5>
     <section class="desc markdown">
       <p>Extending class extends <a href="two_exports/BaseClass-class.html">BaseClass</a>.</p>
 <p>Also check out <a href="two_exports/topLevelVariable.html">topLevelVariable</a>.</p>
-<p>This should not work: linking over to <code>Apple</code>.</p>
+<p>This also should work: linking over to <a href="ex/Apple-class.html">Apple</a>.</p>
     </section>
     
     <section>

From d00d2ea526e627cbd926926bb5363dd6f3c2f055 Mon Sep 17 00:00:00 2001
From: Anton Astashov <anton.astashov@gmail.com>
Date: Mon, 19 Dec 2016 20:07:59 -0600
Subject: [PATCH 2/3] Address @devoncarew feedback

* Add types to declarations
* Add filename/line number to the warnings
* Move the code for gathering all the model elements of a package to the
  package's accessor and cache it.
---
 lib/src/markdown_processor.dart | 99 ++++++++++-----------------------
 lib/src/model.dart              | 63 ++++++++++++++++-----
 2 files changed, 77 insertions(+), 85 deletions(-)

diff --git a/lib/src/markdown_processor.dart b/lib/src/markdown_processor.dart
index 0276add8c3..42f6f41a5c 100644
--- a/lib/src/markdown_processor.dart
+++ b/lib/src/markdown_processor.dart
@@ -9,13 +9,7 @@ import 'dart:convert';
 
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/dart/element/element.dart'
-    show
-        LibraryElement,
-        Element,
-        ConstructorElement,
-        ClassElement,
-        ParameterElement,
-        PropertyAccessorElement;
+    show LibraryElement, Element, ConstructorElement, ClassElement, ParameterElement, PropertyAccessorElement;
 import 'package:html/parser.dart' show parse;
 import 'package:markdown/markdown.dart' as md;
 
@@ -39,27 +33,19 @@ NodeList<CommentReference> _getCommentRefs(ModelElement modelElement) {
   if (modelElement == null) return null;
   if (modelElement.documentation == null && modelElement.canOverride()) {
     var melement = modelElement.overriddenElement;
-    if (melement != null &&
-        melement.element.computeNode() != null &&
-        melement.element.computeNode() is AnnotatedNode) {
-      var docComment = (melement.element.computeNode() as AnnotatedNode)
-          .documentationComment;
+    if (melement != null && melement.element.computeNode() != null && melement.element.computeNode() is AnnotatedNode) {
+      var docComment = (melement.element.computeNode() as AnnotatedNode).documentationComment;
       if (docComment != null) return docComment.references;
       return null;
     }
   }
   if (modelElement.element.computeNode() is AnnotatedNode) {
-    if ((modelElement.element.computeNode() as AnnotatedNode)
-            .documentationComment !=
-        null) {
-      return (modelElement.element.computeNode() as AnnotatedNode)
-          .documentationComment
-          .references;
+    if ((modelElement.element.computeNode() as AnnotatedNode).documentationComment != null) {
+      return (modelElement.element.computeNode() as AnnotatedNode).documentationComment.references;
     }
   } else if (modelElement.element is LibraryElement) {
     // handle anonymous libraries
-    if (modelElement.element.computeNode() == null ||
-        modelElement.element.computeNode().parent == null) {
+    if (modelElement.element.computeNode() == null || modelElement.element.computeNode().parent == null) {
       return null;
     }
     var node = modelElement.element.computeNode().parent.parent;
@@ -73,8 +59,7 @@ NodeList<CommentReference> _getCommentRefs(ModelElement modelElement) {
 }
 
 /// Returns null if element is a parameter.
-MatchingLinkResult _getMatchingLinkElement(
-    String codeRef, ModelElement element, List<CommentReference> commentRefs,
+MatchingLinkResult _getMatchingLinkElement(String codeRef, ModelElement element, List<CommentReference> commentRefs,
     {bool isConstructor: false}) {
   if (commentRefs == null) return new MatchingLinkResult(null, null);
 
@@ -84,8 +69,7 @@ MatchingLinkResult _getMatchingLinkElement(
   for (CommentReference ref in commentRefs) {
     if (ref.identifier.name == codeRef) {
       bool isConstrElement = ref.identifier.staticElement is ConstructorElement;
-      if (isConstructor && isConstrElement ||
-          !isConstructor && !isConstrElement) {
+      if (isConstructor && isConstrElement || !isConstructor && !isConstrElement) {
         refElement = ref.identifier.staticElement;
         break;
       }
@@ -101,8 +85,7 @@ MatchingLinkResult _getMatchingLinkElement(
     // yay we found an accessor that wraps a const, but we really
     // want the top-level field itself
     refElement = (refElement as PropertyAccessorElement).variable;
-    if (refElement.enclosingElement is ClassElement &&
-        (refElement.enclosingElement as ClassElement).isEnum) {
+    if (refElement.enclosingElement is ClassElement && (refElement.enclosingElement as ClassElement).isEnum) {
       isEnum = true;
     }
   }
@@ -115,8 +98,7 @@ MatchingLinkResult _getMatchingLinkElement(
   //
   // Don't search through all libraries in the package, actually search
   // in the current scope.
-  Library refLibrary =
-      element.package.findLibraryFor(refElement, scopedTo: element);
+  Library refLibrary = element.package.findLibraryFor(refElement, scopedTo: element);
 
   if (refLibrary != null) {
     // Is there a way to pull this from a registry of known elements?
@@ -130,30 +112,12 @@ MatchingLinkResult _getMatchingLinkElement(
 }
 
 MatchingLinkResult _findRefElementInLibrary(String codeRef, ModelElement element, List<CommentReference> commentRefs) {
-  final package = element.library.package;
+  final Package package = element.library.package;
   final Map<String, ModelElement> result = {};
-  package.libraries.forEach((library) {
-    final List<ModelElement> modelElements = []
-      ..addAll(library.allClasses)
-      ..addAll(library.constants)
-      ..addAll(library.enums)
-      ..addAll(library.functions)
-      ..addAll(library.properties)
-      ..addAll(library.typedefs);
-
-    library.allClasses.forEach((c) {
-      modelElements.addAll(c.allInstanceMethods);
-      modelElements.addAll(c.allInstanceProperties);
-      modelElements.addAll(c.allOperators);
-      modelElements.addAll(c.staticMethods);
-      modelElements.addAll(c.staticProperties);
-    });
-
-    modelElements.forEach((modelElement) {
-      if (codeRef == modelElement.name || codeRef == modelElement.fullyQualifiedName) {
-        result[modelElement.fullyQualifiedName] = modelElement;
-      }
-    });
+  package.allModelElements.forEach((modelElement) {
+    if (codeRef == modelElement.name || codeRef == modelElement.fullyQualifiedName) {
+      result[modelElement.fullyQualifiedName] = modelElement;
+    }
   });
 
   if (result.isEmpty) {
@@ -161,27 +125,25 @@ MatchingLinkResult _findRefElementInLibrary(String codeRef, ModelElement element
   } else if (result.length == 1) {
     return new MatchingLinkResult(result.values.first, result.values.first.name);
   } else {
-    if (_emitWarning) {
-      print("Abiguous reference '${codeRef}' in '${element.fullyQualifiedName}', " +
-        "we found it in the following elements: ${result.keys.map((k) => "'${k}'").join(", ")}");
-    }
+    // TODO: add --fatal-warning, which would make the app crash in case of ambiguous references
+    print(
+        "Ambiguous reference to [${codeRef}] in '${element.fullyQualifiedName}' (${element.sourceFileName}:${element.lineNumber}). " +
+            "We found matches to the following elements: ${result.keys.map((k) => "'${k}'").join(", ")}");
     return new MatchingLinkResult(null, null);
   }
 }
 
-String _linkDocReference(String reference, ModelElement element,
-    NodeList<CommentReference> commentRefs) {
+String _linkDocReference(String reference, ModelElement element, NodeList<CommentReference> commentRefs) {
   // support for [new Constructor] and [new Class.namedCtr]
   var refs = reference.split(' ');
   MatchingLinkResult result;
   if (refs.length == 2 && refs.first == 'new') {
-    result = _getMatchingLinkElement(refs[1], element, commentRefs,
-        isConstructor: true);
+    result = _getMatchingLinkElement(refs[1], element, commentRefs, isConstructor: true);
   } else {
     result = _getMatchingLinkElement(reference, element, commentRefs);
   }
-  final linkedElement = result.element;
-  final label = result.label ?? reference;
+  final ModelElement linkedElement = result.element;
+  final String label = result.label ?? reference;
   if (linkedElement != null) {
     var classContent = '';
     if (linkedElement.isDeprecated) {
@@ -192,6 +154,7 @@ String _linkDocReference(String reference, ModelElement element,
     return '<a ${classContent}href="${linkedElement.href}">$label</a>';
   } else {
     if (_emitWarning) {
+      // TODO: add --fatal-warning, which would make the app crash in case of ambiguous references
       print("  warning: unresolved doc reference '$reference' (in $element)");
     }
     return '<code>${HTML_ESCAPE.convert(label)}</code>';
@@ -204,8 +167,7 @@ String _renderMarkdownToHtml(String text, [ModelElement element]) {
     return new md.Text(_linkDocReference(name, element, commentRefs));
   }
 
-  return md.markdownToHtml(text,
-      inlineSyntaxes: _markdown_syntaxes, linkResolver: _linkResolver);
+  return md.markdownToHtml(text, inlineSyntaxes: _markdown_syntaxes, linkResolver: _linkResolver);
 }
 
 class Documentation {
@@ -231,16 +193,13 @@ class Documentation {
       s.remove();
     }
     for (var pre in asHtmlDocument.querySelectorAll('pre')) {
-      if (pre.children.isNotEmpty &&
-          pre.children.length != 1 &&
-          pre.children.first.localName != 'code') {
+      if (pre.children.isNotEmpty && pre.children.length != 1 && pre.children.first.localName != 'code') {
         continue;
       }
 
       if (pre.children.isNotEmpty && pre.children.first.localName == 'code') {
         var code = pre.children.first;
-        pre.classes
-            .addAll(code.classes.where((name) => name.startsWith('language-')));
+        pre.classes.addAll(code.classes.where((name) => name.startsWith('language-')));
       }
 
       bool specifiesLanguage = pre.classes.isNotEmpty;
@@ -251,9 +210,7 @@ class Documentation {
 
     // `trim` fixes issue with line ending differences between mac and windows.
     var asHtml = asHtmlDocument.body.innerHtml?.trim();
-    var asOneLiner = asHtmlDocument.body.children.isEmpty
-        ? ''
-        : asHtmlDocument.body.children.first.innerHtml;
+    var asOneLiner = asHtmlDocument.body.children.isEmpty ? '' : asHtmlDocument.body.children.first.innerHtml;
     if (!asOneLiner.startsWith('<p>')) {
       asOneLiner = '<p>$asOneLiner</p>';
     }
diff --git a/lib/src/model.dart b/lib/src/model.dart
index c69017c1f8..e117da4c3d 100644
--- a/lib/src/model.dart
+++ b/lib/src/model.dart
@@ -1425,6 +1425,26 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
     return (_fullyQualifiedName ??= _buildFullyQualifiedName());
   }
 
+  String get sourceFileName {
+    return element.source.fullName;
+  }
+
+  int _lineNumber;
+  bool _isLineNumberComputed = false;
+  int get lineNumber {
+    if (!_isLineNumberComputed) {
+      var node = element.computeNode();
+      if (node is Declaration && node.element != null) {
+        var element = node.element;
+        var lineNumber = lineNumberCache.lineNumber(
+            element.source.fullName, element.nameOffset);
+        _lineNumber = lineNumber + 1;
+      }
+      _isLineNumberComputed = true;
+    }
+    return _lineNumber;
+  }
+
   bool get hasAnnotations => annotations.isNotEmpty;
 
   @override
@@ -2047,6 +2067,31 @@ class Package implements Nameable, Documentable {
     }
     return new Library(e.library, this);
   }
+
+  List<ModelElement> _allModelElements;
+  List<ModelElement> get allModelElements {
+    if (_allModelElements == null) {
+      _allModelElements = [];
+      this.libraries.forEach((library) {
+        _allModelElements
+          ..addAll(library.allClasses)
+          ..addAll(library.constants)
+          ..addAll(library.enums)
+          ..addAll(library.functions)
+          ..addAll(library.properties)
+          ..addAll(library.typedefs);
+
+        library.allClasses.forEach((c) {
+          _allModelElements.addAll(c.allInstanceMethods);
+          _allModelElements.addAll(c.allInstanceProperties);
+          _allModelElements.addAll(c.allOperators);
+          _allModelElements.addAll(c.staticMethods);
+          _allModelElements.addAll(c.staticProperties);
+        });
+      });
+    }
+    return _allModelElements;
+  }
 }
 
 class PackageCategory implements Comparable<PackageCategory> {
@@ -2128,6 +2173,8 @@ abstract class SourceCodeMixin {
     }
   }
 
+  int get lineNumber;
+
   Element get element;
 
   bool get hasSourceCode => config.includeSource && sourceCode.isNotEmpty;
@@ -2210,21 +2257,9 @@ abstract class SourceCodeMixin {
   }
 
   String get _crossdartUrl {
-    if (_lineNumber != null && _crossdartPath != null) {
+    if (lineNumber != null && _crossdartPath != null) {
       String url = "//www.crossdart.info/p/${_crossdartPath}.html";
-      return "${url}#line-${_lineNumber}";
-    } else {
-      return null;
-    }
-  }
-
-  int get _lineNumber {
-    var node = element.computeNode();
-    if (node is Declaration && node.element != null) {
-      var element = node.element;
-      var lineNumber = lineNumberCache.lineNumber(
-          element.source.fullName, element.nameOffset);
-      return lineNumber + 1;
+      return "${url}#line-${lineNumber}";
     } else {
       return null;
     }

From 6930dc627948486daa099fd4dd89cdaa2c65888b Mon Sep 17 00:00:00 2001
From: Anton Astashov <anton.astashov@gmail.com>
Date: Thu, 22 Dec 2016 22:36:53 -0600
Subject: [PATCH 3/3] Address another round of feedback

From now on, if the reference was, for example, `[key]`, we won't match
`material.Widget.key`, we will only match `material.key` (i.e. top-level
`key` symbol). If you still want to match `Widget.key`, you should use
either `[Widget.key]` or `[material.Widget.key]`.
---
 lib/src/markdown_processor.dart               | 21 ++++++---
 lib/src/model.dart                            | 47 ++++++++++++-------
 test/model_test.dart                          | 12 ++++-
 testing/test_package/lib/src/extending.dart   |  2 +-
 testing/test_package/lib/src/mylib.dart       |  3 ++
 .../test_package_docs/ex/Helper-class.html    |  5 ++
 testing/test_package_docs/ex/ex-library.html  |  4 +-
 .../BaseForDocComments/doAwesomeStuff.html    |  2 +-
 .../two_exports/ExtendingClass-class.html     |  2 +-
 9 files changed, 69 insertions(+), 29 deletions(-)

diff --git a/lib/src/markdown_processor.dart b/lib/src/markdown_processor.dart
index 42f6f41a5c..2f041351db 100644
--- a/lib/src/markdown_processor.dart
+++ b/lib/src/markdown_processor.dart
@@ -40,8 +40,9 @@ NodeList<CommentReference> _getCommentRefs(ModelElement modelElement) {
     }
   }
   if (modelElement.element.computeNode() is AnnotatedNode) {
-    if ((modelElement.element.computeNode() as AnnotatedNode).documentationComment != null) {
-      return (modelElement.element.computeNode() as AnnotatedNode).documentationComment.references;
+    final AnnotatedNode annotatedNode = modelElement.element.computeNode();
+    if (annotatedNode.documentationComment != null) {
+      return annotatedNode.documentationComment.references;
     }
   } else if (modelElement.element is LibraryElement) {
     // handle anonymous libraries
@@ -112,13 +113,21 @@ MatchingLinkResult _getMatchingLinkElement(String codeRef, ModelElement element,
 }
 
 MatchingLinkResult _findRefElementInLibrary(String codeRef, ModelElement element, List<CommentReference> commentRefs) {
-  final Package package = element.library.package;
+  final Library library = element.library;
+  final Package package = library.package;
   final Map<String, ModelElement> result = {};
-  package.allModelElements.forEach((modelElement) {
-    if (codeRef == modelElement.name || codeRef == modelElement.fullyQualifiedName) {
+
+  for (final modelElement in package.allModelElements) {
+    if (codeRef == modelElement.fullyQualifiedName) {
+      result[modelElement.fullyQualifiedName] = modelElement;
+    }
+  }
+
+  for (final modelElement in library.allModelElements) {
+    if (codeRef == modelElement.fullyQualifiedNameWithoutLibrary) {
       result[modelElement.fullyQualifiedName] = modelElement;
     }
-  });
+  }
 
   if (result.isEmpty) {
     return new MatchingLinkResult(null, null);
diff --git a/lib/src/model.dart b/lib/src/model.dart
index e117da4c3d..0ca38f7bb3 100644
--- a/lib/src/model.dart
+++ b/lib/src/model.dart
@@ -1215,6 +1215,30 @@ class Library extends ModelElement {
       return _getPackageName(dir.parent);
     }
   }
+
+  List<ModelElement> _allModelElements;
+  List<ModelElement> get allModelElements {
+    if (_allModelElements == null) {
+      final List<ModelElement> result = [];
+      result
+        ..addAll(library.allClasses)
+        ..addAll(library.constants)
+        ..addAll(library.enums)
+        ..addAll(library.functions)
+        ..addAll(library.properties)
+        ..addAll(library.typedefs);
+
+      library.allClasses.forEach((c) {
+        result.addAll(c.allInstanceMethods);
+        result.addAll(c.allInstanceProperties);
+        result.addAll(c.allOperators);
+        result.addAll(c.staticMethods);
+        result.addAll(c.staticProperties);
+      });
+      _allModelElements = result;
+    }
+    return _allModelElements;
+  }
 }
 
 class Method extends ModelElement
@@ -1312,6 +1336,7 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
   String _linkedName;
 
   String _fullyQualifiedName;
+  String _fullyQualifiedNameWithoutLibrary;
 
   // WARNING: putting anything into the body of this seems
   // to lead to stack overflows. Need to make a registry of ModelElements
@@ -1425,10 +1450,12 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
     return (_fullyQualifiedName ??= _buildFullyQualifiedName());
   }
 
-  String get sourceFileName {
-    return element.source.fullName;
+  String get fullyQualifiedNameWithoutLibrary {
+    return (_fullyQualifiedNameWithoutLibrary ??= fullyQualifiedName.split(".").skip(1).join("."));
   }
 
+  String get sourceFileName => element.source.fullName;
+
   int _lineNumber;
   bool _isLineNumberComputed = false;
   int get lineNumber {
@@ -2073,21 +2100,7 @@ class Package implements Nameable, Documentable {
     if (_allModelElements == null) {
       _allModelElements = [];
       this.libraries.forEach((library) {
-        _allModelElements
-          ..addAll(library.allClasses)
-          ..addAll(library.constants)
-          ..addAll(library.enums)
-          ..addAll(library.functions)
-          ..addAll(library.properties)
-          ..addAll(library.typedefs);
-
-        library.allClasses.forEach((c) {
-          _allModelElements.addAll(c.allInstanceMethods);
-          _allModelElements.addAll(c.allInstanceProperties);
-          _allModelElements.addAll(c.allOperators);
-          _allModelElements.addAll(c.staticMethods);
-          _allModelElements.addAll(c.staticProperties);
-        });
+        _allModelElements.addAll(library.allModelElements);
       });
     }
     return _allModelElements;
diff --git a/test/model_test.dart b/test/model_test.dart
index a4547418d2..61e9f057d9 100644
--- a/test/model_test.dart
+++ b/test/model_test.dart
@@ -276,7 +276,15 @@ void main() {
       test(
           'link to a name in another library in this package, but is not imported into this library, is codeified',
           () {
-        expect(docsAsHtml, contains('<a href="anonymous_library/doesStuff.html">doesStuff</a>'));
+        expect(docsAsHtml, contains('<code>doesStuff</code>'));
+      });
+
+      test(
+          'link to unresolved name in the library in this package still should be linked',
+          () {
+        final Class helperClass = exLibrary.classes.firstWhere((c) => c.name == 'Helper');
+        expect(helperClass.documentationAsHtml, contains('<a href="ex/Apple-class.html">Apple</a>'));
+        expect(helperClass.documentationAsHtml, contains('<a href="ex/B-class.html">B</a>'));
       });
 
       test(
@@ -427,7 +435,7 @@ void main() {
       expect(resolved, isNotNull);
       expect(resolved,
           contains('<a href="two_exports/BaseClass-class.html">BaseClass</a>'));
-      expect(resolved, contains('linking over to <a href="ex/Apple-class.html">Apple</a>.'));
+      expect(resolved, contains('linking over to <code>Apple</code>.'));
     });
 
     test('references to class and constructors', () {
diff --git a/testing/test_package/lib/src/extending.dart b/testing/test_package/lib/src/extending.dart
index fae34934b3..c60eb1d95f 100644
--- a/testing/test_package/lib/src/extending.dart
+++ b/testing/test_package/lib/src/extending.dart
@@ -8,5 +8,5 @@ int topLevelVariable = 1;
 ///
 /// Also check out [topLevelVariable].
 ///
-/// This also should work: linking over to [Apple].
+/// This should not work: linking over to [Apple].
 class ExtendingClass extends BaseClass {}
diff --git a/testing/test_package/lib/src/mylib.dart b/testing/test_package/lib/src/mylib.dart
index ed58a02a0d..d9e423d539 100644
--- a/testing/test_package/lib/src/mylib.dart
+++ b/testing/test_package/lib/src/mylib.dart
@@ -2,6 +2,9 @@ library src.mylib;
 
 void helperFunction(String message) => print(message);
 
+/// Even unresolved references in the same library should be resolved
+/// [Apple]
+/// [ex.B]
 class Helper {
   Helper();
 
diff --git a/testing/test_package_docs/ex/Helper-class.html b/testing/test_package_docs/ex/Helper-class.html
index 778ce5147d..28f3b5ddaf 100644
--- a/testing/test_package_docs/ex/Helper-class.html
+++ b/testing/test_package_docs/ex/Helper-class.html
@@ -134,6 +134,11 @@ <h5><a href="ex/ex-library.html">ex</a></h5>
 
   <div class="col-xs-12 col-sm-9 col-md-8 main-content">
 
+    <section class="desc markdown">
+      <p>Even unresolved references in the same library should be resolved
+<a href="ex/Apple-class.html">Apple</a>
+<a href="ex/B-class.html">B</a></p>
+    </section>
     
 
 
diff --git a/testing/test_package_docs/ex/ex-library.html b/testing/test_package_docs/ex/ex-library.html
index 294126e41b..3ebaea5f64 100644
--- a/testing/test_package_docs/ex/ex-library.html
+++ b/testing/test_package_docs/ex/ex-library.html
@@ -380,7 +380,9 @@ <h2>Classes</h2>
           <span class="name "><a href="ex/Helper-class.html">Helper</a></span>
         </dt>
         <dd>
-          <p></p>
+          <p>Even unresolved references in the same library should be resolved
+<a href="ex/Apple-class.html">Apple</a>
+<a href="ex/B-class.html">B</a></p>
         </dd>
         <dt id="Klass">
           <span class="name "><a href="ex/Klass-class.html">Klass</a></span>
diff --git a/testing/test_package_docs/fake/BaseForDocComments/doAwesomeStuff.html b/testing/test_package_docs/fake/BaseForDocComments/doAwesomeStuff.html
index 8e579efa69..d090335382 100644
--- a/testing/test_package_docs/fake/BaseForDocComments/doAwesomeStuff.html
+++ b/testing/test_package_docs/fake/BaseForDocComments/doAwesomeStuff.html
@@ -117,7 +117,7 @@ <h5><a href="fake/BaseForDocComments-class.html">BaseForDocComments</a></h5>
 <p>Reference to a top-level const in another library <a href="ex/incorrectDocReferenceFromEx-constant.html">incorrectDocReferenceFromEx</a></p>
 <p>Reference to prefixed-name from another lib <a href="css/theOnlyThingInTheLibrary.html">css.theOnlyThingInTheLibrary</a> xx</p>
 <p>Reference to a name that exists in this package, but is not imported
-in this library <a href="anonymous_library/doesStuff.html">doesStuff</a> xx</p>
+in this library <code>doesStuff</code> xx</p>
 <p>Reference to a name of a class from an import of a library that exported
 the name <a href="two_exports/BaseClass-class.html">BaseClass</a> xx</p>
     </section>
diff --git a/testing/test_package_docs/two_exports/ExtendingClass-class.html b/testing/test_package_docs/two_exports/ExtendingClass-class.html
index f7f4c382fc..7ac640892a 100644
--- a/testing/test_package_docs/two_exports/ExtendingClass-class.html
+++ b/testing/test_package_docs/two_exports/ExtendingClass-class.html
@@ -95,7 +95,7 @@ <h5><a href="two_exports/two_exports-library.html">two_exports</a></h5>
     <section class="desc markdown">
       <p>Extending class extends <a href="two_exports/BaseClass-class.html">BaseClass</a>.</p>
 <p>Also check out <a href="two_exports/topLevelVariable.html">topLevelVariable</a>.</p>
-<p>This also should work: linking over to <a href="ex/Apple-class.html">Apple</a>.</p>
+<p>This should not work: linking over to <code>Apple</code>.</p>
     </section>
     
     <section>