handle doc references to top-level constants

Closes #762

order imports

Squashed commit of the following:

commit 4e528dc
Author: Seth Ladd <[email protected]>
Date:   Wed Aug 5 08:56:09 2015 -0700

    order imports

commit 05f7941
Author: Seth Ladd <[email protected]>
Date:   Wed Aug 5 08:54:12 2015 -0700

    disable formatting checks, because of version diffs

commit f36c0fd
Author: Seth Ladd <[email protected]>
Date:   Tue Aug 4 19:16:39 2015 -0700

    upgrade analyzer, add more tests, skip tests we don't have a solution for right now

commit d8a730d
Author: Seth Ladd <[email protected]>
Date:   Tue Aug 4 17:52:12 2015 -0700

    add a skip to a test, we'll take care of later

commit f614435
Merge: 802c3ef 6b1d987
Author: Seth Ladd <[email protected]>
Date:   Tue Aug 4 17:37:20 2015 -0700

    Merge remote-tracking branch 'origin/master' into sl-underscores

commit 802c3ef
Author: Seth Ladd <[email protected]>
Date:   Tue Aug 4 16:07:40 2015 -0700

    WIP

commit 1250b18
Author: Seth Ladd <[email protected]>
Date:   Tue Aug 4 12:50:22 2015 -0700

    lots more tests

commit dea14d4
Author: Seth Ladd <[email protected]>
Date:   Mon Aug 3 22:40:31 2015 -0700

    handle doc references to top-level constants

commit a66b2db
Author: Seth Ladd <[email protected]>
Date:   Mon Aug 3 22:40:09 2015 -0700

    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,9 +22,6 @@ import 'package:markdown/markdown.dart' as md;
 import 'src/html_utils.dart' show htmlEscape;
 import 'src/model.dart';
 
-const _leftChar = '[';
-const _rightChar = ']';
-
 final List<md.InlineSyntax> _markdown_syntaxes = [new _InlineCodeSyntax()];
 
 // We don't emit warnings currently: #572.
@@ -164,16 +163,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/debug.dart

@@ -0,0 +1,7 @@
+library debugger_helper;
+
+import "dart:developer" as dev;
+
+get debugger =>
+    const String.fromEnvironment('DEBUG') == null ? _nodebugger : dev.debugger;
+_nodebugger({when, message}) {}

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

@@ -11,9 +11,11 @@ import 'package:analyzer/src/generated/resolver.dart';
 import 'package:analyzer/src/generated/utilities_dart.dart' show ParameterKind;
 import 'package:quiver/core.dart';
 
+import 'debug.dart';
 import 'html_utils.dart';
 import 'model_utils.dart';
 import 'package_meta.dart';
+
 import '../markdown_processor.dart';
 
 int byName(a, b) => a.name.toUpperCase().compareTo(b.name.toUpperCase());
@@ -84,12 +86,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);
     }
@@ -239,13 +241,13 @@ abstract class ModelElement implements Comparable {
 
   ElementType get modelType => _modelType;
 
-  /// Returns the [ModelElement] that encloses this.
-  ModelElement get enclosingElement {
+  /// Returns the [ClassElement] that encloses this.
+  Class get enclosingClass {
     // A class's enclosing element is a library, and there isn't a
     // modelelement for a library.
     if (element.enclosingElement != null &&
         element.enclosingElement is ClassElement) {
-      return new ModelElement.from(element.enclosingElement, library);
+      return new ModelElement.from(element.enclosingElement, library) as Class;
     } else {
       return null;
     }
@@ -258,10 +260,13 @@ abstract class ModelElement implements Comparable {
     if (!package.isDocumented(this.element)) {
       return htmlEscape(name);
     }
+
     if (name.startsWith('_')) {
       return htmlEscape(name);
     }
-    Class c = enclosingElement;
+
+    // this smells like it's in the wrong place
+    Class c = enclosingClass;
     if (c != null && c.name.startsWith('_')) {
       return '${c.name}.${htmlEscape(name)}';
     }
@@ -292,8 +297,8 @@ abstract class ModelElement implements Comparable {
           buf.write(' <span class="parameter-name">${p.name}</span>');
         }
         buf.write('(');
-        buf.write(p.modelType.element
-            .linkedParams(showNames: showNames, showMetadata: showMetadata));
+        buf.write(p.modelType.element.linkedParams(
+            showNames: showNames, showMetadata: showMetadata));
         buf.write(')');
       } else if (p.modelType != null && p.modelType.element != null) {
         var mt = p.modelType;
@@ -414,29 +419,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_WITH_TWO_UNDERSCORES');
+    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) {
@@ -682,9 +700,8 @@ class Library extends ModelElement {
   }
 
   List<Class> get classes {
-    return _allClasses
-        .where((c) => !c.isErrorOrException)
-        .toList(growable: false);
+    return _allClasses.where((c) => !c.isErrorOrException).toList(
+        growable: false);
   }
 
   List<Class> get allClasses => _allClasses;
@@ -781,9 +798,9 @@ class Class extends ModelElement {
   }
 
   List<TypeParameter> get _typeParameters => _cls.typeParameters.map((f) {
-        var lib = new Library(f.enclosingElement.library, package);
-        return new TypeParameter(f, lib);
-      }).toList();
+    var lib = new Library(f.enclosingElement.library, package);
+    return new TypeParameter(f, lib);
+  }).toList();
 
   String get kind => 'class';
 
@@ -1212,8 +1229,7 @@ class Enum extends Class {
 
   @override
   List<EnumField> get instanceProperties {
-    return super
-        .instanceProperties
+    return super.instanceProperties
         .map((Field p) => new EnumField(p.element, p.library))
         .toList(growable: false);
   }
@@ -1437,7 +1453,7 @@ class Constructor extends ModelElement {
   @override
   String get name {
     String constructorName = element.name;
-    Class c = enclosingElement;
+    Class c = enclosingClass;
     if (constructorName.isEmpty) {
       return c.name;
     } else {
@@ -1706,10 +1722,8 @@ class ElementType {
 
   ElementType get _returnType {
     var rt = (_type as FunctionType).returnType;
-    return new ElementType(
-        rt,
-        new ModelElement.from(rt.element,
-            new Library(_element.library.element, _element.package)));
+    return new ElementType(rt, new ModelElement.from(
+        rt.element, new Library(_element.library.element, _element.package)));
   }
 
   ModelElement get returnElement {
@@ -1723,9 +1737,9 @@ class ElementType {
 
   List<ElementType> get typeArguments =>
       (_type as ParameterizedType).typeArguments.map((f) {
-        var lib = new Library(f.element.library, _element.package);
-        return new ElementType(f, new ModelElement.from(f.element, lib));
-      }).toList();
+    var lib = new Library(f.element.library, _element.package);
+    return new ElementType(f, new ModelElement.from(f.element, lib));
+  }).toList();
 
   String get linkedName {
     if (_linkedName != null) return _linkedName;

pubspec.lock

@@ -4,7 +4,7 @@ packages:
   analyzer:
     description: analyzer
     source: hosted
-    version: "0.25.2"
+    version: "0.26.0"
   ansicolor:
     description: ansicolor
     source: hosted
@@ -88,7 +88,7 @@ packages:
   markdown:
     description: markdown
     source: hosted
-    version: "0.7.1+2"
+    version: "0.7.1+3"
   matcher:
     description: matcher
     source: hosted
@@ -148,7 +148,7 @@ packages:
   shelf_static:
     description: shelf_static
     source: hosted
-    version: "0.2.2"
+    version: "0.2.3"
   shelf_web_socket:
     description: shelf_web_socket
     source: hosted
@@ -180,7 +180,7 @@ packages:
   test:
     description: test
     source: hosted
-    version: "0.12.3+8"
+    version: "0.12.3+9"
   unscripted:
     description: unscripted
     source: hosted

pubspec.yaml

@@ -7,7 +7,7 @@ homepage: https://github.com/dart-lang/dartdoc
 environment:
   sdk: '>=1.9.0 <2.0.0' # when we go to 1.12, bump analyzer version
 dependencies:
-  analyzer: ^0.25.0
+  analyzer: '>=0.25.0 <0.27.0'
   args: ^0.13.0
   cli_util: ^0.0.1
   html: ^0.12.1