handle doc references to top-level constants

Author: sethladd

lib/markdown_processor.dart

@@ -11,7 +11,9 @@ import 'package:analyzer/src/generated/element.dart'
         LibraryElement,
         Element,
         ConstructorElement,
+        CompilationUnitElement,
         ClassMemberElement,
+        TopLevelVariableElement,
         PropertyAccessorElement;
 import 'package:html/dom.dart' show Document;
 import 'package:html/parser.dart' show parse;
@@ -20,8 +22,7 @@ import 'package:markdown/markdown.dart' as md;
 import 'src/html_utils.dart' show htmlEscape;
 import 'src/model.dart';
 
-const _leftChar = '[';
-const _rightChar = ']';
+import 'src/debug.dart';
 
 final List<md.InlineSyntax> _markdown_syntaxes = [new _InlineCodeSyntax()];
 
@@ -85,6 +86,7 @@ class Documentation {
 
 String renderMarkdownToHtml(String text, [ModelElement element]) {
   md.Node _linkResolver(String name) {
+    //debugger(when: element != null && element.name == 'doAwesomeStuff');
     NodeList<CommentReference> commentRefs = _getCommentRefs(element);
     return new md.Text(_linkDocReference(name, element, commentRefs));
   }
@@ -147,6 +149,8 @@ NodeList<CommentReference> _getCommentRefs(ModelElement modelElement) {
 String _getMatchingLink(
     String codeRef, ModelElement element, List<CommentReference> commentRefs,
     {bool isConstructor: false}) {
+  debugger(when: element.name == 'short');
+
   if (commentRefs == null) return null;
 
   Element refElement;
@@ -164,16 +168,15 @@ String _getMatchingLink(
 
   if (refElement == null) return null;
 
-  Library refLibrary;
-  var e = refElement is ClassMemberElement ||
-          refElement is PropertyAccessorElement
-      ? refElement.enclosingElement
-      : refElement;
+  if (refElement is PropertyAccessorElement &&
+      refElement.enclosingElement is CompilationUnitElement) {
+    // yay we found an accessor that wraps a const, but we really
+    // want the top-level field itself
+    refElement = (refElement as PropertyAccessorElement).variable;
+  }
+
+  Library refLibrary = element.package.findLibraryFor(refElement);
 
-  // If e is a ParameterElement, it's
-  // never going to be in a library. So refLibrary is going to be null.
-  refLibrary = element.package.libraries.firstWhere(
-      (lib) => lib.hasInNamespace(e), orElse: () => null);
   if (refLibrary != null) {
     // Is there a way to pull this from a registry of known elements?
     // Seems like we're creating too many objects this way.

lib/src/html_utils.dart

@@ -8,19 +8,6 @@ import 'dart:convert';
 
 String htmlEscape(String text) => HTML_ESCAPE.convert(text);
 
-String escapeBrackets(String text) {
-  return text.replaceAll('>', '_').replaceAll('<', '_');
-}
-
-String stringEscape(String text, String quoteType) {
-  return text
-      .replaceAll('\\', r'\\')
-      .replaceAll(quoteType, "\\${quoteType}")
-      .replaceAllMapped(_escapeRegExp, (m) {
-    return _escapeMap[m.input];
-  });
-}
-
 String stripComments(String str) {
   if (str == null) return null;
 

lib/src/model.dart

@@ -14,6 +14,7 @@ import 'package:quiver/core.dart';
 import 'html_utils.dart';
 import 'model_utils.dart';
 import 'package_meta.dart';
+import 'debug.dart';
 import '../markdown_processor.dart';
 
 int byName(a, b) => a.name.toUpperCase().compareTo(b.name.toUpperCase());
@@ -84,12 +85,12 @@ abstract class ModelElement implements Comparable {
     if (e is MethodElement && !e.isOperator) {
       return new Method(e, library);
     }
-    if (e is PropertyAccessorElement) {
-      return new Accessor(e, library);
-    }
     if (e is TopLevelVariableElement) {
       return new TopLevelVariable(e, library);
     }
+    if (e is PropertyAccessorElement) {
+      return new Accessor(e, library);
+    }
     if (e is TypeParameterElement) {
       return new TypeParameter(e, library);
     }
@@ -414,29 +415,42 @@ class Package {
 
   String toString() => isSdk ? 'SDK' : 'Package $name';
 
-  bool isDocumented(Element element) {
+  Library findLibraryFor(final Element element) {
     if (element is LibraryElement) {
-      return _libraries.any((lib) => lib.element == element);
+      // will equality work here? or should we check names?
+      return _libraries.firstWhere((lib) => lib.element == element,
+          orElse: () => null);
     }
 
     Element el;
     if (element is ClassMemberElement || element is PropertyAccessorElement) {
-      el = element.enclosingElement;
+      if (element.enclosingElement is! CompilationUnitElement) {
+        el = element.enclosingElement;
+      } else {
+        // in this case, element is an accessor for a library-level variable,
+        // likely a const. We, in this case, actually don't want the enclosing
+        // element because it's a compilation unit, whatever that is.
+        el = element;
+      }
     } else if (element is TopLevelVariableElement) {
-      TopLevelVariableElement variable = element;
-      if (variable.getter != null) {
-        el = variable.getter;
-      } else if (variable.setter != null) {
-        el = variable.setter;
+      final TopLevelVariableElement variableElement = element;
+      if (variableElement.getter != null) {
+        el = variableElement.getter;
+      } else if (variableElement.setter != null) {
+        el = variableElement.setter;
       } else {
-        el = variable;
+        el = variableElement;
       }
     } else {
       el = element;
     }
-    return _libraries.any((lib) => lib.hasInNamespace(el));
+    debugger(when: element.name == 'NAME_SINGLEUNDERSCORE');
+    return _libraries.firstWhere((lib) => lib.hasInNamespace(el),
+        orElse: () => null);
   }
 
+  bool isDocumented(Element element) => findLibraryFor(element) != null;
+
   String get href => 'index.html';
 
   Library _getLibraryFor(Element e) {

test/model_test.dart

@@ -170,6 +170,8 @@ void main() {
     Class specialList;
     Class subForDocComments;
 
+    ModelFunction short;
+
     setUp(() {
       incorrectReference = exLibrary.constants
           .firstWhere((c) => c.name == 'incorrectDocReference');
@@ -193,6 +195,17 @@ void main() {
 
       subForDocComments =
           fakeLibrary.classes.firstWhere((c) => c.name == 'SubForDocComments');
+
+      short = fakeLibrary.functions.firstWhere((f) => f.name == 'short');
+    });
+
+    test('multi-underscore names in brackets do not become italicized', () {
+      expect(short.documentation, contains('[NAME_WITH_TWO_UNDERSCORES]'));
+      expect(short.documentation, contains('[NAME_SINGLEUNDERSCORE]'));
+      expect(short.documentationAsHtml, contains(
+          '<a href="fake/NAME_WITH_TWO_UNDERSCORES.html">NAME_WITH_TWO_UNDERSCORES</a>'));
+      expect(short.documentationAsHtml, contains(
+          '<a href="fake/NAME_SINGLEUNDERSCORE.html">NAME_SINGLEUNDERSCORE</a>'));
     });
 
     test('still has brackets inside code blocks', () {

test_package/lib/fake.dart

@@ -84,6 +84,15 @@ const ConstantClass CUSTOM_CLASS = const ConstantClass('custom');
 /// Getting up in the morning can be hard.
 const String UP = 'up';
 
+const String NAME_SINGLEUNDERSCORE = 'yay bug hunting';
+
+const String NAME_WITH_TWO_UNDERSCORES = 'episode seven better be good';
+
+/// Testing [NAME_WITH_TWO_UNDERSCORES] should not be italicized.
+///
+/// This name should link correctly: [NAME_SINGLEUNDERSCORE]
+void short() {}
+
 /// Dynamic-typed down.
 @deprecated
 const DOWN = 'down';
@@ -376,6 +385,8 @@ class BaseForDocComments {
   /// Takes a [value] and returns a String.
   ///
   /// This methods is inside of [BaseForDocComments]
+  ///
+  /// Also [NAME_WITH_TWO_UNDERSCORES]
   String doAwesomeStuff(int value) => null;
 }