diff --git a/pkg/docgen/bin/docgen.dart b/pkg/docgen/bin/docgen.dart index 51ba13a6da6..16792d3a4c9 100644 --- a/pkg/docgen/bin/docgen.dart +++ b/pkg/docgen/bin/docgen.dart @@ -40,11 +40,9 @@ void main(List arguments) { docgen(files, packageRoot: options['package-root'], - outputToYaml: !options['json'], includePrivate: options['include-private'], includeSdk: includeSdk, parseSdk: options['parse-sdk'], - append: options['append'] && new Directory(options['out']).existsSync(), introFileName: introduction, out: options['out'], excludeLibraries: excludedLibraries, @@ -103,11 +101,6 @@ ArgParser _initArgParser() { callback: (verbose) { if (verbose) Logger.root.level = Level.FINEST; }); - parser.addFlag('json', abbr: 'j', - help: 'Outputs to JSON. If negated, outputs to YAML. ' - 'If --append is used, it takes the file-format of the previous ' - 'run stated in library_list.json, ignoring the flag.', - negatable: true, defaultsTo: true); parser.addFlag('include-private', help: 'Flag to include private declarations.', negatable: false); parser.addFlag('include-sdk', @@ -119,9 +112,6 @@ ArgParser _initArgParser() { defaultsTo: false, negatable: false); parser.addOption('package-root', help: 'Sets the package root of the library being analyzed.'); - parser.addFlag('append', - help: 'Append to the docs folder, library_list.json and index.txt', - defaultsTo: false, negatable: false); parser.addFlag('compile', help: 'Clone the documentation viewer repo locally ' '(if not already present) and compile with dart2js', defaultsTo: false, negatable: false); diff --git a/pkg/docgen/lib/docgen.dart b/pkg/docgen/lib/docgen.dart index f56bf694e7c..f35037c33ae 100644 --- a/pkg/docgen/lib/docgen.dart +++ b/pkg/docgen/lib/docgen.dart @@ -38,8 +38,7 @@ export 'src/package_helpers.dart' show packageNameFor; /// /// Returned Future completes with true if document generation is successful. Future docgen(List files, {String packageRoot, - bool outputToYaml: false, bool includePrivate: false, - bool includeSdk: false, bool parseSdk: false, bool append: false, + bool includePrivate: false, bool includeSdk: false, bool parseSdk: false, String introFileName: '', String out: gen.DEFAULT_OUTPUT_DIRECTORY, List excludeLibraries: const [], bool includeDependentPackages: false, bool compile: false, @@ -49,8 +48,8 @@ Future docgen(List files, {String packageRoot, if (!noDocs) { viewer.ensureMovedViewerCode(); result = gen.generateDocumentation(files, packageRoot: packageRoot, - outputToYaml: outputToYaml, includePrivate: includePrivate, - includeSdk: includeSdk, parseSdk: parseSdk, append: append, + includePrivate: includePrivate, + includeSdk: includeSdk, parseSdk: parseSdk, introFileName: introFileName, out: out, excludeLibraries: excludeLibraries, includeDependentPackages: includeDependentPackages, diff --git a/pkg/docgen/lib/src/dart2yaml.dart b/pkg/docgen/lib/src/dart2yaml.dart deleted file mode 100644 index ac0a8ee718d..00000000000 --- a/pkg/docgen/lib/src/dart2yaml.dart +++ /dev/null @@ -1,84 +0,0 @@ -// Copyright (c) 2013, 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. - -/** - * This library is used to convert data from a map to a YAML string. - */ -library docgen.dart2yaml; - -/** - * Gets a String representing the input Map in YAML format. - */ -String getYamlString(Map documentData) { - StringBuffer yaml = new StringBuffer(); - _addLevel(yaml, documentData, 0); - return yaml.toString(); -} - -/** - * This recursive function builds a YAML string from [documentData] and - * adds it to [yaml]. - * The [level] input determines the indentation of the block being processed. - * The [isList] input determines whether [documentData] is a member of an outer - * lists of maps. A map must be preceeded with a '-' if it is to exist at the - * same level of indentation in the YAML output as other members of the list. - */ -void _addLevel(StringBuffer yaml, Map documentData, int level, - {bool isList: false}) { - // The order of the keys could be nondeterministic, but it is insufficient - // to just sort the keys no matter what, as their order could be significant - // (i.e. parameters to a method). The order of the keys should be enforced - // by the caller of this function. - var keys = documentData.keys.toList(); - keys.forEach((key) { - _calcSpaces(level, yaml); - // Only the first entry of the map should be preceeded with a '-' since - // the map is a member of an outer list and the map as a whole must be - // marked as a single member of that list. See example 2.4 at - // http://www.yaml.org/spec/1.2/spec.html#id2759963 - if (isList && key == keys.first) { - yaml.write("- "); - level++; - } - yaml.write("\"$key\" : "); - if (documentData[key] is Map) { - yaml.write("\n"); - _addLevel(yaml, documentData[key], level + 1); - } else if (documentData[key] is List) { - var elements = documentData[key]; - yaml.write("\n"); - elements.forEach( (element) { - if (element is Map) { - _addLevel(yaml, element, level + 1, isList: true); - } else { - _calcSpaces(level + 1, yaml); - yaml.write("- ${_processElement(element)}"); - } - }); - } else { - yaml.write(_processElement(documentData[key])); - } - }); -} - -/** - * Returns an escaped String form of the inputted element. - */ -String _processElement(var element) { - var contents = element.toString() - .replaceAll('\\', r'\\') - .replaceAll('"', r'\"') - .replaceAll('\n', r'\n'); - return '"$contents"\n'; -} - -/** - * Based on the depth in the file, this function returns the correct spacing - * for an element in the YAML output. - */ -void _calcSpaces(int spaceLevel, StringBuffer yaml) { - for (int i = 0; i < spaceLevel; i++) { - yaml.write(" "); - } -} \ No newline at end of file diff --git a/pkg/docgen/lib/src/generator.dart b/pkg/docgen/lib/src/generator.dart index e1478ff04ee..236619dab0b 100644 --- a/pkg/docgen/lib/src/generator.dart +++ b/pkg/docgen/lib/src/generator.dart @@ -24,7 +24,6 @@ import '../../../../sdk/lib/_internal/compiler/implementation/mirrors/source_mir import '../../../../sdk/lib/_internal/compiler/implementation/source_file_provider.dart'; import '../../../../sdk/lib/_internal/libraries.dart'; -import 'dart2yaml.dart'; import 'io.dart'; import 'library_helpers.dart'; import 'models.dart'; @@ -62,7 +61,7 @@ String _dartBinary; /// Returned Future completes with true if document generation is successful. Future generateDocumentation(List files, {String packageRoot, bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false, bool - parseSdk: false, bool append: false, String introFileName: '', out: + parseSdk: false, String introFileName: '', out: DEFAULT_OUTPUT_DIRECTORY, List excludeLibraries: const [], bool includeDependentPackages: false, String startPage, String dartBinary, String pubScript}) { @@ -72,7 +71,7 @@ Future generateDocumentation(List files, {String packageRoot, bool logger.onRecord.listen((record) => print(record.message)); - _ensureOutputDirectory(out, append); + _ensureOutputDirectory(out); var updatedPackageRoot = _obtainPackageRoot(packageRoot, parseSdk, files); var requestedLibraries = _findLibrariesToDocument(files, @@ -105,8 +104,7 @@ Future generateDocumentation(List files, {String packageRoot, bool librariesToDocument.removeWhere((x) => _excluded.contains( dart2js_util.nameOf(x))); _documentLibraries(librariesToDocument, includeSdk: includeSdk, - outputToYaml: outputToYaml, append: append, parseSdk: parseSdk, - introFileName: introFileName, startPage: startPage); + parseSdk: parseSdk, introFileName: introFileName, startPage: startPage); return true; }); } @@ -134,7 +132,7 @@ Future getMirrorSystem(List libraries, } /// Writes [text] to a file in the output directory. -void _writeToFile(String text, String filename, {bool append: false}) { +void _writeToFile(String text, String filename) { if (text == null) return; Directory dir = new Directory(_outputDirectory); if (!dir.existsSync()) { @@ -154,7 +152,7 @@ void _writeToFile(String text, String filename, {bool append: false}) { } } File file = new File(path.join(_outputDirectory, filename)); - file.writeAsStringSync(text, mode: append ? FileMode.APPEND : FileMode.WRITE); + file.writeAsStringSync(text, mode: FileMode.WRITE); } /// Resolve all the links in the introductory comments for a given library or @@ -188,9 +186,8 @@ int _indexableComparer(Indexable a, Indexable b) { } /// Creates documentation for filtered libraries. -void _documentLibraries(List libs, {bool includeSdk: false, bool - outputToYaml: true, bool append: false, bool parseSdk: false, String - introFileName: '', String startPage}) { +void _documentLibraries(List libs, {bool includeSdk: 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:')) { @@ -214,45 +211,26 @@ void _documentLibraries(List libs, {bool includeSdk: false, bool // Outputs a JSON file with all libraries and their preview comments. // This will help the viewer know what libraries are available to read in. - Map libraryMap; - - if (append) { - var docsDir = listDir(_outputDirectory); - if (!docsDir.contains('$_outputDirectory/library_list.json')) { - throw new StateError('No library_list.json'); - } - libraryMap = JSON.decode(new File('$_outputDirectory/library_list.json' - ).readAsStringSync()); - libraryMap['libraries'].addAll(filteredEntities.where((e) => e is Library - ).map((e) => e.previewMap)); - var intro = libraryMap['introduction']; - var spacing = intro.isEmpty ? '' : '

'; - libraryMap['introduction'] = - "$intro$spacing${_readIntroductionFile(introFileName, includeSdk)}"; - outputToYaml = libraryMap['filetype'] == 'yaml'; - } else { - libraryMap = { + Map libraryMap = { 'libraries': filteredEntities.where((e) => e is Library).map((e) => e.previewMap).toList(), 'introduction': _readIntroductionFile(introFileName, includeSdk), - 'filetype': outputToYaml ? 'yaml' : 'json' + 'filetype': 'json' }; - } - _writeOutputFiles(libraryMap, filteredEntities, outputToYaml, append, - startPage); + _writeOutputFiles(libraryMap, filteredEntities, startPage); } -/// Output all of the libraries and classes into json or yaml files for -/// consumption by a viewer. +/// Output all of the libraries and classes into json files for consumption by a +/// viewer. void _writeOutputFiles(Map libraryMap, Iterable - filteredEntities, bool outputToYaml, bool append, String startPage) { + filteredEntities, String startPage) { if (startPage != null) libraryMap['start-page'] = startPage; _writeToFile(JSON.encode(libraryMap), 'library_list.json'); // Output libraries and classes to file after all information is generated. filteredEntities.where((e) => e is Class || e is Library).forEach((output) { - _writeIndexableToFile(output, outputToYaml); + _writeIndexableToFile(output); }); // Outputs all the qualified names documented with their type. @@ -260,40 +238,26 @@ void _writeOutputFiles(Map libraryMap, Iterable var sortedEntities = filteredEntities.map((e) => '${e.qualifiedName} ${e.typeName}').toList()..sort(); - _writeToFile(sortedEntities.join('\n') + '\n', 'index.txt', append: append); + _writeToFile(sortedEntities.join('\n') + '\n', 'index.txt'); 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) { - var outputFile = result.fileName; - var output; - if (outputToYaml) { - output = getYamlString(result.toMap()); - outputFile = outputFile + '.yaml'; - } else { - output = JSON.encode(result.toMap()); - outputFile = outputFile + '.json'; - } +void _writeIndexableToFile(Indexable result) { + var outputFile = result.fileName + '.json'; + var output = JSON.encode(result.toMap()); _writeToFile(output, outputFile); } /// Set the location of the ouput directory, and ensure that the location is /// available on the file system. -void _ensureOutputDirectory(String outputDirectory, bool append) { +void _ensureOutputDirectory(String outputDirectory) { _outputDirectory = outputDirectory; - if (!append) { - var dir = new Directory(_outputDirectory); - if (dir.existsSync()) dir.deleteSync(recursive: true); - } + var dir = new Directory(_outputDirectory); + if (dir.existsSync()) dir.deleteSync(recursive: true); } /// Analyzes set of libraries and provides a mirror system which can be used @@ -326,8 +290,8 @@ Future analyzeLibraries(List libraries, String /// /// If packageRoot is not explicitly passed, we examine the files we're /// documenting to attempt to find a package root. -String _obtainPackageRoot(String packageRoot, bool parseSdk, List files) - { +String _obtainPackageRoot(String packageRoot, bool parseSdk, + List files) { if (packageRoot == null && !parseSdk) { var type = FileSystemEntity.typeSync(files.first); if (type == FileSystemEntityType.DIRECTORY) { diff --git a/utils/apidoc/docgen.gyp b/utils/apidoc/docgen.gyp index 49af512d519..a6a9142650c 100644 --- a/utils/apidoc/docgen.gyp +++ b/utils/apidoc/docgen.gyp @@ -78,14 +78,13 @@ '--package-root=<(PRODUCT_DIR)/packages', '../../pkg/docgen/bin/docgen.dart', '--out=<(PRODUCT_DIR)/api_docs/docgen', - '--json', '--include-sdk', '--no-include-dependent-packages', '--package-root=<(PRODUCT_DIR)/packages', '--exclude-lib=async_helper', '--exclude-lib=expect', '--exclude-lib=docgen', - '../../pkg', + '../../pkg' ], 'message': 'Running docgen: <(_action)', },