'Find-as-you-type'-search in dartdoc/apidoc.

pkg/dartdoc/dartdoc.dart

 // Copyright (c) 2012, 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.
 
 /**
  * To generate docs for a library, run this script with the path to an
  * entrypoint .dart file, like:
  *
  *     $ dart dartdoc.dart foo.dart
  *
@@ skipping 11 matching lines @@
 #import('mirrors/mirrors.dart');
 #import('mirrors/mirrors_util.dart');
 #import('mirrors/dart2js_mirror.dart', prefix: 'dart2js');
 #import('classify.dart');
 #import('markdown.dart', prefix: 'md');
 #import('../../lib/compiler/implementation/scanner/scannerlib.dart',
         prefix: 'dart2js');
 #import('../../lib/compiler/implementation/library_map.dart');
 
 #source('comment_map.dart');
+#source('nav.dart');
 #source('utils.dart');
 
 // TODO(johnniwinther): Note that [IN_SDK] gets initialized to true when this
 // file is modified by the SDK deployment script. If you change, be sure to test
 // that dartdoc still works when run from the built SDK directory.
 final bool IN_SDK = false;
 
 /**
  * Generates completely static HTML containing everything you need to browse
  * the docs. The only client side behavior is trivial stuff like syntax
@@ skipping 110 matching lines @@
   // Compile the client-side code to JS.
   final clientScript = (dartdoc.mode == MODE_STATIC) ? 'static' : 'live-nav';
   Future compiled = compileScript(
     scriptDir.append('client-$clientScript.dart'),
     dartdoc.outputDir.append('client-$clientScript.js'));
 
   Future filesCopied = copyDirectory(scriptDir.append('static'),
                                      dartdoc.outputDir);
 
   Futures.wait([compiled, filesCopied]).then((_) {
+    dartdoc.cleanup();
     print('Documented ${dartdoc._totalLibraries} libraries, '
           '${dartdoc._totalTypes} types, and '
           '${dartdoc._totalMembers} members.');
   });
 }
 
 void printUsage() {
   print('''
 Usage dartdoc [options] <entrypoint(s)>
 [options] include
@@ skipping 133 matching lines @@
    * want the client-side behavior to be. The value for this should be one of
    * the `MODE_` constants.
    */
   int mode = MODE_LIVE_NAV;
 
   /**
    * Generates the App Cache manifest file, enabling offline doc viewing.
    */
   bool generateAppCache = false;
 
+  /** Path to the dartdoc directory. */
+  Path dartdocPath;
+
   /** Path to generate HTML files into. */
   Path outputDir = const Path('docs');
 
   /**
    * The title used for the overall generated output. Set this to change it.
    */
   String mainTitle = 'Dart Documentation';
 
   /**
    * The URL that the Dart logo links to. Defaults "index.html", the main
@@ skipping 54 matching lines @@
   Path _filePath;
 
   /** The file currently being written to. */
   StringBuffer _file;
 
   int _totalLibraries = 0;
   int _totalTypes = 0;
   int _totalMembers = 0;
 
   Dartdoc()
-    : _comments = new CommentMap() {
+      : _comments = new CommentMap(),
+        dartdocPath = scriptDir {
+
     // Patch in support for [:...:]-style code to the markdown parser.
     // TODO(rnystrom): Markdown already has syntax for this. Phase this out?
     md.InlineParser.syntaxes.insertRange(0, 1,
         new md.CodeSyntax(@'\[\:((?:.|\n)*?)\:\]'));
 
     md.setImplicitLinkResolver((name) => resolveNameReference(name,
             currentLibrary: _currentLibrary, currentType: _currentType,
             currentMember: _currentMember));
   }
 
@@ skipping 75 matching lines @@
     // Sort the libraries by name (not key).
     _sortedLibraries = new List<LibraryMirror>.from(
         compilation.mirrors.libraries.getValues().filter(
             shouldIncludeLibrary));
     _sortedLibraries.sort((x, y) {
       return x.simpleName.toUpperCase().compareTo(
           y.simpleName.toUpperCase());
     });
 
     // Generate the docs.
-    if (mode == MODE_LIVE_NAV) docNavigationJson();
+    if (mode == MODE_LIVE_NAV) {
+      docNavigationJson();
+    } else {
+      docNavigationDart();
+    }
 
     docIndex();
     for (final library in _sortedLibraries) {
       docLibrary(library);
     }
 
     if (generateAppCache) {
       generateAppCacheManifest();
     }
   }
@@ skipping 85 matching lines @@
     }
 
     if (searchEngineId != null) {
       writeln(
         '''
         <form action="$searchResultsUrl" id="search-box">
           <input type="hidden" name="cx" value="$searchEngineId">
           <input type="hidden" name="ie" value="UTF-8">
           <input type="hidden" name="hl" value="en">
           <input type="search" name="q" id="q" autocomplete="off"
-              placeholder="Search">
+              class="search-input" placeholder="Search">
         </form>
         ''');
+    } else {
+      writeln(
+        '''
+        <div id="search-box">
+          <input type="search" name="q" id="q" autocomplete="off"
+              class="search-input" placeholder="Search">
+        </div>
+        ''');
     }
 
-    writeln('</div>');
+    writeln(
+      '''
+      </div>
+      <div class="drop-down" id="drop-down"></div>

[Lasse Reichstein Nielsen, 2012/08/20 13:07:58]

Why both id and class? Are there any other elements with class drop-down?

[Johnni Winther, 2012/08/23 10:19:50]

I just dislike referring to 'id' in CSS and 'class' in single-point queries, so
'id' for element identity and 'class' for its style.

+      ''');
 
     docNavigation();
     writeln('<div class="content">');
   }
 
   String get clientScript() {
     switch (mode) {
       case MODE_STATIC:   return 'client-static';
       case MODE_LIVE_NAV: return 'client-live-nav';
       default: throw 'Unknown mode $mode.';
@@ skipping 46 matching lines @@
   void docIndexLibrary(LibraryMirror library) {
     writeln('<h4>${a(libraryUrl(library), library.simpleName)}</h4>');
   }
 
   /**
    * Walks the libraries and creates a JSON object containing the data needed
    * to generate navigation for them.
    */
   void docNavigationJson() {
     startFile('nav.json');
-
-    final libraryMap = {};
-
-    for (final library in _sortedLibraries) {
-      docLibraryNavigationJson(library, libraryMap);
-    }
-
-    writeln(JSON.stringify(libraryMap));
+    writeln(JSON.stringify(createNavigationInfo()));
     endFile();
   }
 
-  void docLibraryNavigationJson(LibraryMirror library, Map libraryMap) {
+  void docNavigationDart() {
+    final dir = new Directory.fromPath(tmpPath);
+    if (!dir.existsSync()) {
+      // TODO(3914): Hack to avoid 'file already exists' exception
+      // thrown due to invalid result from dir.existsSync() (probably due to
+      // race conditions).
+      try {
+        dir.createSync();
+      } catch (DirectoryIOException e) {
+        // Ignore.

[Lasse Reichstein Nielsen, 2012/08/20 13:07:58]

I still don't like this.
It's really a bad idea to ignore an exception without checking what caused it.
Maybe it isn't "file already exists"?

[Johnni Winther, 2012/08/23 10:19:50]

There seems to be a solution to 3914 underway.

+      }
+    }
+    String jsonString = JSON.stringify(createNavigationInfo());
+    String dartString = jsonString.replaceAll(@"$", @"\$");
+    final filePath = tmpPath.append('nav.dart');
+    writeString(new File.fromPath(filePath),
+        'get json() => $dartString;');
+  }
+
+  Path get tmpPath() => dartdocPath.append('tmp');
+
+  void cleanup() {
+    final dir = new Directory.fromPath(tmpPath);
+    if (dir.existsSync()) {
+      dir.deleteRecursivelySync();
+    }
+  }
+
+  List createNavigationInfo() {
+    final libraryList = [];
+    for (final library in _sortedLibraries) {
+      docLibraryNavigationJson(library, libraryList);
+    }
+    return libraryList;
+  }
+
+  void docLibraryNavigationJson(LibraryMirror library, List libraryList) {
+    var libraryInfo = {};
+    libraryInfo[NAME] = library.simpleName;
+    final List members = docMembersJson(library.declaredMembers);
+    if (!members.isEmpty()) {
+      libraryInfo[MEMBERS] = members;
+    }
+
     final types = [];
-
     for (InterfaceMirror type in orderByName(library.types.getValues())) {
       if (type.isPrivate) continue;
 
-      final kind = type.isClass ? 'class' : 'interface';
-      final url = typeUrl(type);
-      types.add({ 'name': typeName(type), 'kind': kind, 'url': url });
+      var typeInfo = {};
+      typeInfo[NAME] = type.simpleName;
+      if (type.isClass) {
+        typeInfo[KIND] = CLASS;
+      } else if (type.isInterface) {
+        typeInfo[KIND] = INTERFACE;
+      } else {
+        assert(type.isTypedef);
+        typeInfo[KIND] = TYPEDEF;
+      }
+      final List typeMembers = docMembersJson(type.declaredMembers);
+      if (!typeMembers.isEmpty()) {
+        typeInfo[MEMBERS] = typeMembers;
+      }
+
+      if (!type.declaration.typeVariables.isEmpty()) {
+        final typeVariables = [];
+        for (final typeVariable in type.declaration.typeVariables) {
+          typeVariables.add(typeVariable.simpleName);
+        }
+        typeInfo[ARGS] = Strings.join(typeVariables, ', ');
+      }
+      types.add(typeInfo);
+    }
+    if (!types.isEmpty()) {
+      libraryInfo[TYPES] = types;
     }
 
-    libraryMap[library.simpleName] = types;
+    libraryList.add(libraryInfo);
+  }
+
+  List docMembersJson(Map<Object,MemberMirror> memberMap) {
+    final members = [];
+    for (MemberMirror member in orderByName(memberMap.getValues())) {
+      if (member.isPrivate) continue;
+
+      var memberInfo = {};
+      if (member.isField) {
+        memberInfo[NAME] = member.simpleName;
+        memberInfo[KIND] = FIELD;
+      } else {
+        MethodMirror method = member;
+        if (method.isConstructor) {
+          if (method.constructorName != '') {
+            memberInfo[NAME] = '${method.simpleName}.${method.constructorName}';
+            memberInfo[KIND] = CONSTRUCTOR;
+          } else {
+            memberInfo[NAME] = member.simpleName;
+            memberInfo[KIND] = CONSTRUCTOR;
+          }
+        } else if (method.isOperator) {
+          memberInfo[NAME] = '${method.simpleName} ${method.operatorName}';
+          memberInfo[KIND] = METHOD;
+        } else if (method.isSetter) {
+          memberInfo[NAME] = member.simpleName;
+          memberInfo[KIND] = SETTER;
+        } else if (method.isGetter) {
+          memberInfo[NAME] = member.simpleName;
+          memberInfo[KIND] = GETTER;
+        } else {
+          memberInfo[NAME] = member.simpleName;
+          memberInfo[KIND] = METHOD;
+        }
+      }
+      var anchor = memberAnchor(member);
+      if (anchor != memberInfo[NAME]) {
+        memberInfo[LINK_NAME] = anchor;
+      }
+      members.add(memberInfo);
+    }
+    return members;
   }
 
   void docNavigation() {
     writeln(
         '''
         <div class="nav">
         ''');
 
     if (mode == MODE_STATIC) {
       for (final library in _sortedLibraries) {
@@ skipping 585 matching lines @@
     // Always get the generic type to strip off any type parameters or
     // arguments. If the type isn't generic, genericType returns `this`, so it
     // works for non-generic types too.
     return '${sanitize(type.library.simpleName)}/'
            '${type.declaration.simpleName}.html';
   }
 
   /** Gets the URL for the documentation for [member]. */
   String memberUrl(MemberMirror member) {
     String url = typeUrl(member.surroundingDeclaration);
-    if (!member.isConstructor) {
-      return '$url#${member.simpleName}';
-    }
-    assert (member is MethodMirror);
-    if (member.constructorName == '') {
-      return '$url#new:${member.simpleName}';
-    }
-    return '$url#new:${member.simpleName}.${member.constructorName}';
+    return '$url#${memberAnchor(member)}';
   }
 
   /** Gets the anchor id for the document for [member]. */
   String memberAnchor(MemberMirror member) {
-    return '${member.simpleName}';
+    if (member.isField) {
+      return member.simpleName;
+    }
+    MethodMirror method = member;
+    if (method.isConstructor) {
+      if (method.constructorName == '') {
+        return method.simpleName;
+      } else {
+        return '${method.simpleName}.${method.constructorName}';
+      }
+    } else if (method.isOperator) {
+      return '${method.simpleName} ${method.operatorName}';
+    } else if (method.isSetter) {
+      return '${method.simpleName}=';
+    } else {
+      return method.simpleName;
+    }
   }
 
   /**
    * Creates a hyperlink. Handles turning the [href] into an appropriate
    * relative path from the current file.
    */
   String a(String href, String contents, [String css]) {
     // Mark outgoing external links, mainly so we can style them.
     final rel = isAbsolute(href) ? ' ref="external"' : '';
     final cssClass = css == null ? '' : ' class="$css"';
@@ skipping 86 matching lines @@
   }
 
   /** Generates a human-friendly string representation for a type. */
   typeName(TypeMirror type, [bool showBounds = false]) {
     if (type.isVoid) {
       return 'void';
     }
     if (type is TypeVariableMirror) {
       return type.simpleName;
     }
-    assert (type is InterfaceMirror);
+    assert(type is InterfaceMirror);
 
     // See if it's a generic type.
     if (type.isDeclaration) {
       final typeParams = [];
       for (final typeParam in type.declaration.typeVariables) {
         if (showBounds &&
             (typeParam.bound != null) &&
             !typeParam.bound.isObject) {
           final bound = typeName(typeParam.bound, showBounds: true);
           typeParams.add('${typeParam.simpleName} extends $bound');
@@ skipping 163 matching lines @@
   }
 
   /**
    * Returns [:true:] if [type] should be regarded as an exception.
    */
   bool isException(TypeMirror type) {
     return type.simpleName.endsWith('Exception');
   }
 }