pkg/docgen: sort output files

pkg/docgen/lib/src/generator.dart

 // Copyright (c) 2014, 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.
 
 library docgen.generator;
 
 import 'dart:async';
+import 'dart:collection';
 import 'dart:convert';
 import 'dart:io';
 
 import 'package:markdown/markdown.dart' as markdown;
 import 'package:path/path.dart' as path;
 
 import '../../../../sdk/lib/_internal/compiler/compiler.dart' as api;
 import '../../../../sdk/lib/_internal/compiler/implementation/filenames.dart';
 import '../../../../sdk/lib/_internal/compiler/implementation/mirrors/analyze.dart'
     as dart2js;
@@ skipping 146 matching lines @@
   var introText = defaultText;
   if (fileName.isNotEmpty) {
     var introFile = new File(fileName);
     introText = introFile.existsSync() ? introFile.readAsStringSync() :
         defaultText;
   }
   return markdown.markdownToHtml(introText, linkResolver: linkResolver,
       inlineSyntaxes: MARKDOWN_SYNTAXES);
 }
 
+int _indexableComparer(Indexable a, Indexable b) {
+  if (a is Library && b is Library) {
+    var compare = a.packageName.compareTo(b.packageName);
+    if (compare == 0) {
+      compare = a.name.compareTo(b.name);
+    }
+    return compare;
+  }
+
+  if (a is Library) return -1;
+  if (b is Library) return 1;
+
+  return a.qualifiedName.compareTo(b.qualifiedName);
+}

[Alan Knight, 2014/04/14 17:33:30]

Why can't we just compare the qualified name of libraries, when that's what we
do for everything else?

[kevmoo, 2014/04/14 17:35:37]

Because core libraries don't have a qualified prefix, so they end up sorted in
the middle of the content (after the packages starting with "C")

This fix ensures that dart:core libs show up first

+
 /// Creates documentation for filtered libraries.
 void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false, bool
     outputToYaml: true, bool append: false, bool parseSdk: false, String
     introFileName: '', String startPage}) {
   libs.forEach((lib) {
     // Files belonging to the SDK have a uri that begins with 'dart:'.
     if (includeSdk || !lib.uri.toString().startsWith('dart:')) {
       generateLibrary(lib);
     }
   });
 
-  var filteredEntities = new Set<Indexable>();
+  var filteredEntities = new SplayTreeSet<Indexable>(_indexableComparer);
   for (Map<String, Set<Indexable>> firstLevel in mirrorToDocgen.values) {
     for (Set<Indexable> items in firstLevel.values) {
       for (Indexable item in items) {
         if (isFullChainVisible(item)) {
           if (item is! Method ||
               (item is Method && item.methodInheritedFrom == null)) {
             filteredEntities.add(item);
           }
         }
       }
@@ skipping 42 matching lines @@
   filteredEntities.where((e) => e is Class || e is Library).forEach((output) {
     _writeIndexableToFile(output, outputToYaml);
   });
 
   // Outputs all the qualified names documented with their type.
   // This will help generate search results.
   var sortedEntities = filteredEntities.map((e) =>
       '${e.qualifiedName} ${e.typeName}').toList()..sort();
 
   _writeToFile(sortedEntities.join('\n') + '\n', 'index.txt', append: append);
-  var index = new Map.fromIterables(filteredEntities.map((e) => e.qualifiedName
-      ), filteredEntities.map((e) => e.typeName));
+  var index = new SplayTreeMap.fromIterable(filteredEntities,
+      key: (e) => e.qualifiedName, value: (e) => e.typeName);
+
   if (append) {
     var previousIndex = JSON.decode(new File('$_outputDirectory/index.json'
         ).readAsStringSync());
     index.addAll(previousIndex);
   }
   _writeToFile(JSON.encode(index), 'index.json');
 }
 
 /// Helper method to serialize the given Indexable out to a file.
 void _writeIndexableToFile(Indexable result, bool outputToYaml) {
@@ skipping 171 matching lines @@
   return sdk;
 }
 
 /// Currently left public for testing purposes. :-/
 void generateLibrary(dart2js_mirrors.Dart2JsLibraryMirror library) {
   var result = new Library(library);
   result.updateLibraryPackage(library);
   logger.fine('Generated library for ${result.name}');
 }
 
-
 /// If we can't find the SDK introduction text, which will happen if running
 /// from a snapshot and using --parse-sdk or --include-sdk, then use this
 /// hard-coded version. This should be updated to be consistent with the text
 /// in docgen/doc/sdk-introduction.md
 const _DEFAULT_SDK_INTRODUCTION =
     """
 Welcome to the Dart API reference documentation,
 covering the official Dart API libraries.
 Some of the most fundamental Dart libraries include:
 
@@ skipping 31 matching lines @@
   * [Samples](http://www.dartlang.org/samples/)
   * [A Tour of the Dart Libraries](http://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html)
 
 This API reference is automatically generated from the source code in the
 [Dart project](https://code.google.com/p/dart/).
 If you'd like to contribute to this documentation, see
 [Contributing](https://code.google.com/p/dart/wiki/Contributing)
 and
 [Writing API Documentation](https://code.google.com/p/dart/wiki/WritingApiDocumentation).
 """;