| // 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. |
| |
| /// **docgen** is a tool for creating machine readable representations of Dart |
| /// code metadata, including: classes, members, comments and annotations. |
| /// |
| /// docgen is run on a `.dart` file or a directory containing `.dart` files. |
| /// |
| /// $ dart docgen.dart [OPTIONS] [FILE/DIR] |
| /// |
| /// This creates files called `docs/<library_name>.yaml` in your current |
| /// working directory. |
| library docgen; |
| |
| import 'dart:convert'; |
| import 'dart:io'; |
| import 'dart:async'; |
| |
| import 'package:logging/logging.dart'; |
| import 'package:markdown/markdown.dart' as markdown; |
| import 'package:path/path.dart' as path; |
| import 'package:yaml/yaml.dart'; |
| |
| import 'src/dart2yaml.dart'; |
| import 'src/io.dart'; |
| import 'src/mdn.dart'; |
| import 'src/models.dart'; |
| import 'src/utils.dart'; |
| |
| import '../../../sdk/lib/_internal/compiler/compiler.dart' as api; |
| import '../../../sdk/lib/_internal/compiler/implementation/filenames.dart'; |
| import '../../../sdk/lib/_internal/compiler/implementation/mirrors/dart2js_mirrors.dart' |
| as dart2js_mirrors; |
| import '../../../sdk/lib/_internal/compiler/implementation/mirrors/analyze.dart' |
| as dart2js; |
| import '../../../sdk/lib/_internal/compiler/implementation/mirrors/source_mirrors.dart'; |
| import '../../../sdk/lib/_internal/compiler/implementation/mirrors/mirrors_util.dart' |
| as dart2js_util; |
| import '../../../sdk/lib/_internal/compiler/implementation/source_file_provider.dart'; |
| import '../../../sdk/lib/_internal/libraries.dart'; |
| |
| const _DEFAULT_OUTPUT_DIRECTORY = 'docs'; |
| |
| /// Annotations that we do not display in the viewer. |
| const List<String> _SKIPPED_ANNOTATIONS = const [ |
| 'metadata.DocsEditable', '_js_helper.JSName', '_js_helper.Creates', |
| '_js_helper.Returns']; |
| |
| /// Support for [:foo:]-style code comments to the markdown parser. |
| final List<markdown.InlineSyntax> _MARKDOWN_SYNTAXES = |
| [new markdown.CodeSyntax(r'\[:\s?((?:.|\n)*?)\s?:\]')]; |
| |
| /// 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: |
| |
| * [dart:core](#dart:core): |
| Core functionality such as strings, numbers, collections, errors, |
| dates, and URIs. |
| * [dart:html](#dart:html): |
| DOM manipulation for web apps. |
| * [dart:io](#dart:io): |
| I/O for command-line apps. |
| |
| Except for dart:core, you must import a library before you can use it. |
| Here's an example of importing dart:html, dart:math, and a |
| third popular library called |
| [polymer.dart](http://www.dartlang.org/polymer-dart/): |
| |
| import 'dart:html'; |
| import 'dart:math'; |
| import 'package:polymer/polymer.dart'; |
| |
| Polymer.dart is an example of a library that isn't |
| included in the Dart download, |
| but is easy to get and update using the _pub package manager_. |
| For information on finding, using, and publishing libraries (and more) |
| with pub, see |
| [pub.dartlang.org](http://pub.dartlang.org). |
| |
| The main site for learning and using Dart is |
| [www.dartlang.org](http://www.dartlang.org). |
| Check out these pages: |
| |
| * [Dart homepage](http://www.dartlang.org) |
| * [Tutorials](http://www.dartlang.org/docs/tutorials/) |
| * [Programmer's Guide](http://www.dartlang.org/docs/) |
| * [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). |
| """; |
| |
| /// Docgen constructor initializes the link resolver for markdown parsing. |
| /// Also initializes the command line arguments. |
| /// |
| /// [packageRoot] is the packages directory of the directory being analyzed. |
| /// If [includeSdk] is `true`, then any SDK libraries explicitly imported will |
| /// also be documented. |
| /// If [parseSdk] is `true`, then all Dart SDK libraries will be documented. |
| /// This option is useful when only the SDK libraries are needed. |
| /// If [compile] is `true`, then after generating the documents, compile the |
| /// viewer with dart2js. |
| /// If [serve] is `true`, then after generating the documents we fire up a |
| /// simple server to view the documentation. |
| /// |
| /// Returned Future completes with true if document generation is successful. |
| Future<bool> docgen(List<String> files, {String packageRoot, |
| bool outputToYaml: false, bool includePrivate: false, bool includeSdk: false, |
| bool parseSdk: false, bool append: false, String introFileName: '', |
| String out: _DEFAULT_OUTPUT_DIRECTORY, |
| List<String> excludeLibraries : const [], |
| bool includeDependentPackages: false, bool compile: false, |
| bool serve: false, bool noDocs: false, String startPage, String pubScript, |
| String dartBinary}) { |
| var result; |
| if (!noDocs) { |
| _Viewer.ensureMovedViewerCode(); |
| result = _Generator.generateDocumentation(files, packageRoot: packageRoot, |
| outputToYaml: outputToYaml, includePrivate: includePrivate, |
| includeSdk: includeSdk, parseSdk: parseSdk, append: append, |
| introFileName: introFileName, out: out, |
| excludeLibraries: excludeLibraries, |
| includeDependentPackages: includeDependentPackages, |
| startPage: startPage, pubScript: pubScript, dartBinary: dartBinary); |
| _Viewer.addBackViewerCode(); |
| if (compile || serve) { |
| result.then((success) { |
| if (success) { |
| _createViewer(serve); |
| } |
| }); |
| } |
| } else if (compile || serve) { |
| _createViewer(serve); |
| } |
| return result; |
| } |
| |
| void _createViewer(bool serve) { |
| _Viewer._clone(); |
| _Viewer._compile(); |
| if (serve) { |
| _Viewer._runServer(); |
| } |
| } |
| |
| /// Analyzes set of libraries by getting a mirror system and triggers the |
| /// documentation of the libraries. |
| Future<MirrorSystem> getMirrorSystem(List<Uri> libraries, |
| {String packageRoot, bool parseSdk: false}) { |
| if (libraries.isEmpty) throw new StateError('No Libraries.'); |
| |
| // Finds the root of SDK library based off the location of docgen. |
| // We have two different places to look, depending if we're in a development |
| // repo or in a built SDK, either sdk or dart-sdk respectively |
| var root = _Generator._rootDirectory; |
| var sdkRoot = path.normalize(path.absolute(path.join(root, 'sdk'))); |
| if (!new Directory(sdkRoot).existsSync()) { |
| sdkRoot = path.normalize(path.absolute(path.join(root, 'dart-sdk'))); |
| } |
| _Generator.logger.info('SDK Root: ${sdkRoot}'); |
| return _Generator._analyzeLibraries(libraries, sdkRoot, |
| packageRoot: packageRoot); |
| } |
| |
| /// For types that we do not explicitly create or have not yet created in our |
| /// entity map (like core types). |
| class DummyMirror implements Indexable { |
| DeclarationMirror mirror; |
| /// The library that contains this element, if any. Used as a hint to help |
| /// determine which object we're referring to when looking up this mirror in |
| /// our map. |
| Indexable owner; |
| DummyMirror(this.mirror, [this.owner]); |
| |
| String get docName { |
| if (mirror == null) return ''; |
| if (mirror is LibraryMirror) { |
| return dart2js_util.qualifiedNameOf(mirror).replaceAll('.','-'); |
| } |
| var mirrorOwner = mirror.owner; |
| if (mirrorOwner == null) return dart2js_util.qualifiedNameOf(mirror); |
| var simpleName = dart2js_util.nameOf(mirror); |
| if (mirror is MethodMirror && (mirror as MethodMirror).isConstructor) { |
| // We name constructors specially -- repeating the class name and a |
| // "-" to separate the constructor from its name (if any). |
| simpleName = '${dart2js_util.nameOf(mirrorOwner)}-$simpleName'; |
| } |
| return Indexable.getDocgenObject(mirrorOwner, owner).docName + '.' + |
| simpleName; |
| } |
| |
| bool get isPrivate => mirror == null? false : mirror.isPrivate; |
| |
| String get packageName { |
| var libMirror = _getOwningLibraryFromMirror(mirror); |
| if (libMirror != null) { |
| return Library._packageName(libMirror); |
| } |
| return ''; |
| } |
| |
| String get packagePrefix => packageName == null || packageName.isEmpty ? |
| '' : '$packageName/'; |
| |
| LibraryMirror _getOwningLibraryFromMirror(DeclarationMirror mirror) { |
| if (mirror is LibraryMirror) return mirror; |
| if (mirror == null) return null; |
| return _getOwningLibraryFromMirror(mirror.owner); |
| } |
| } |
| |
| /// Top level documentation traversal and generation object. |
| /// |
| /// Yes, everything in this class is used statically so this technically doesn't |
| /// need to be its own class, but it's grouped together for semantic separation |
| /// from the other classes and functionality in this library. |
| class _Generator { |
| /// The directory where the output docs are generated. |
| static String _outputDirectory; |
| |
| /// This is set from the command line arguments flag --include-private |
| static bool _includePrivate = false; |
| |
| /// Library names to explicitly exclude. |
| /// |
| /// Set from the command line option |
| /// --exclude-lib. |
| static List<String> _excluded; |
| |
| /// The path of the pub script. |
| static String _pubScript; |
| |
| /// The path of Dart binary. |
| static String _dartBinary; |
| |
| /// Logger for printing out progress of documentation generation. |
| static Logger logger = new Logger('Docgen'); |
| |
| /// Docgen constructor initializes the link resolver for markdown parsing. |
| /// Also initializes the command line arguments. |
| /// |
| /// [packageRoot] is the packages directory of the directory being analyzed. |
| /// If [includeSdk] is `true`, then any SDK libraries explicitly imported will |
| /// also be documented. |
| /// If [parseSdk] is `true`, then all Dart SDK libraries will be documented. |
| /// This option is useful when only the SDK libraries are needed. |
| /// |
| /// Returned Future completes with true if document generation is successful. |
| static Future<bool> generateDocumentation(List<String> files, |
| {String packageRoot, bool outputToYaml: true, bool includePrivate: false, |
| bool includeSdk: false, bool parseSdk: false, bool append: false, |
| String introFileName: '', out: _DEFAULT_OUTPUT_DIRECTORY, |
| List<String> excludeLibraries : const [], |
| bool includeDependentPackages: false, String startPage, |
| String dartBinary, String pubScript}) { |
| _excluded = excludeLibraries; |
| _includePrivate = includePrivate; |
| _pubScript = pubScript; |
| _dartBinary = dartBinary; |
| |
| logger.onRecord.listen((record) => print(record.message)); |
| |
| _ensureOutputDirectory(out, append); |
| var updatedPackageRoot = _obtainPackageRoot(packageRoot, parseSdk, files); |
| |
| var requestedLibraries = _findLibrariesToDocument(files, |
| includeDependentPackages); |
| |
| var allLibraries = []..addAll(requestedLibraries); |
| if (includeSdk) { |
| allLibraries.addAll(_listSdk()); |
| } |
| |
| return getMirrorSystem(allLibraries, packageRoot: updatedPackageRoot, |
| parseSdk: parseSdk) |
| .then((MirrorSystem mirrorSystem) { |
| if (mirrorSystem.libraries.isEmpty) { |
| throw new StateError('No library mirrors were created.'); |
| } |
| Indexable._initializeTopLevelLibraries(mirrorSystem); |
| |
| var availableLibraries = mirrorSystem.libraries.values.where( |
| (each) => each.uri.scheme == 'file'); |
| var availableLibrariesByPath = new Map.fromIterables( |
| availableLibraries.map((each) => each.uri), |
| availableLibraries); |
| var librariesToDocument = requestedLibraries.map( |
| (each) => availableLibrariesByPath.putIfAbsent(each, |
| () => throw "Missing library $each")).toList(); |
| librariesToDocument.addAll( |
| (includeSdk || parseSdk) ? Indexable._sdkLibraries : []); |
| librariesToDocument.removeWhere( |
| (x) => _excluded.contains(dart2js_util.nameOf(x))); |
| _documentLibraries(librariesToDocument, includeSdk: includeSdk, |
| outputToYaml: outputToYaml, append: append, parseSdk: parseSdk, |
| introFileName: introFileName, startPage: startPage); |
| return true; |
| }); |
| } |
| |
| /// Writes [text] to a file in the output directory. |
| static void _writeToFile(String text, String filename, {bool append: false}) { |
| if (text == null) return; |
| Directory dir = new Directory(_outputDirectory); |
| if (!dir.existsSync()) { |
| dir.createSync(); |
| } |
| if (path.split(filename).length > 1) { |
| var splitList = path.split(filename); |
| for (int i = 0; i < splitList.length; i++) { |
| var level = splitList[i]; |
| } |
| for (var level in path.split(filename)) { |
| var subdir = new Directory(path.join(_outputDirectory, |
| path.dirname(filename))); |
| if (!subdir.existsSync()) { |
| subdir.createSync(); |
| } |
| } |
| } |
| File file = new File(path.join(_outputDirectory, filename)); |
| file.writeAsStringSync(text, |
| mode: append ? FileMode.APPEND : FileMode.WRITE); |
| } |
| |
| /// Resolve all the links in the introductory comments for a given library or |
| /// package as specified by [filename]. |
| static String _readIntroductionFile(String fileName, bool includeSdk) { |
| var linkResolver = (name) => Indexable.globalFixReference(name); |
| var defaultText = includeSdk ? _DEFAULT_SDK_INTRODUCTION : ''; |
| 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); |
| } |
| |
| /// Creates documentation for filtered libraries. |
| static 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>(); |
| for (Map<String, Set<Indexable>> firstLevel in |
| Indexable._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); |
| } |
| } |
| } |
| } |
| } |
| |
| // 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<String, dynamic> 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 ? '' : '<br/><br/>'; |
| libraryMap['introduction'] = |
| "$intro$spacing${_readIntroductionFile(introFileName, includeSdk)}"; |
| outputToYaml = libraryMap['filetype'] == 'yaml'; |
| } else { |
| libraryMap = { |
| 'libraries' : filteredEntities.where((e) => |
| e is Library).map((e) => e.previewMap).toList(), |
| 'introduction' : _readIntroductionFile(introFileName, includeSdk), |
| 'filetype' : outputToYaml ? 'yaml' : 'json' |
| }; |
| } |
| _writeOutputFiles(libraryMap, filteredEntities, outputToYaml, append, |
| startPage); |
| } |
| |
| /// Output all of the libraries and classes into json or yaml files for |
| /// consumption by a viewer. |
| static void _writeOutputFiles(Map<String, dynamic> libraryMap, |
| Iterable<Indexable> filteredEntities, bool outputToYaml, bool append, |
| 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); |
| }); |
| |
| // 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)); |
| 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. |
| static 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'; |
| } |
| _writeToFile(output, outputFile); |
| } |
| |
| /// Set the location of the ouput directory, and ensure that the location is |
| /// available on the file system. |
| static void _ensureOutputDirectory(String outputDirectory, bool append) { |
| _outputDirectory = outputDirectory; |
| if (!append) { |
| var dir = new Directory(_outputDirectory); |
| if (dir.existsSync()) dir.deleteSync(recursive: true); |
| } |
| } |
| |
| /// Helper accessor to determine the full pathname of the root of the dart |
| /// checkout. We can be in one of three situations: |
| /// 1) Running from pkg/docgen/bin/docgen.dart |
| /// 2) Running from a snapshot in a build, |
| /// e.g. xcodebuild/ReleaseIA32/dart-sdk/bin |
| /// 3) Running from a built distribution, |
| /// e.g. ...somename/dart-sdk/bin/snapshots |
| static String get _rootDirectory { |
| var scriptDir = path.absolute(path.dirname(Platform.script.toFilePath())); |
| var root = scriptDir; |
| var base = path.basename(root); |
| // When we find dart-sdk or sdk we are one level below the root. |
| while (base != 'dart-sdk' && base != 'sdk' && base != 'pkg') { |
| root = path.dirname(root); |
| base = path.basename(root); |
| if (root == base) { |
| // We have reached the root of the filesystem without finding anything. |
| throw new FileSystemException( |
| "Cannot find SDK directory starting from ", |
| scriptDir); |
| } |
| } |
| return path.dirname(root); |
| } |
| |
| /// Analyzes set of libraries and provides a mirror system which can be used |
| /// for static inspection of the source code. |
| static Future<MirrorSystem> _analyzeLibraries(List<Uri> libraries, |
| String libraryRoot, {String packageRoot}) { |
| SourceFileProvider provider = new CompilerSourceFileProvider(); |
| api.DiagnosticHandler diagnosticHandler = |
| (new FormattingDiagnosticHandler(provider) |
| ..showHints = false |
| ..showWarnings = false) |
| .diagnosticHandler; |
| Uri libraryUri = new Uri.file(appendSlash(libraryRoot)); |
| Uri packageUri = null; |
| if (packageRoot != null) { |
| packageUri = new Uri.file(appendSlash(packageRoot)); |
| } |
| return dart2js.analyze(libraries, libraryUri, packageUri, |
| provider.readStringFromUri, diagnosticHandler, |
| ['--preserve-comments', '--categories=Client,Server']) |
| ..catchError((error) { |
| logger.severe('Error: Failed to create mirror system. '); |
| // TODO(janicejl): Use the stack trace package when bug is resolved. |
| // Currently, a string is thrown when it fails to create a mirror |
| // system, and it is not possible to use the stack trace. BUG(#11622) |
| // To avoid printing the stack trace. |
| exit(1); |
| }); |
| } |
| |
| /// For this run of docgen, determine the packageRoot value. |
| /// |
| /// If packageRoot is not explicitly passed, we examine the files we're |
| /// documenting to attempt to find a package root. |
| static String _obtainPackageRoot(String packageRoot, bool parseSdk, |
| List<String> files) { |
| if (packageRoot == null && !parseSdk) { |
| var type = FileSystemEntity.typeSync(files.first); |
| if (type == FileSystemEntityType.DIRECTORY) { |
| var files2 = listDir(files.first, recursive: true); |
| // Return '' means that there was no pubspec.yaml and therefor no p |
| // ackageRoot. |
| packageRoot = files2.firstWhere((f) => |
| f.endsWith('${path.separator}pubspec.yaml'), orElse: () => ''); |
| if (packageRoot != '') { |
| packageRoot = path.join(path.dirname(packageRoot), 'packages'); |
| } |
| } else if (type == FileSystemEntityType.FILE) { |
| logger.warning('WARNING: No package root defined. If Docgen fails, try ' |
| 'again by setting the --package-root option.'); |
| } |
| } |
| logger.info('Package Root: ${packageRoot}'); |
| return path.normalize(path.absolute(packageRoot)); |
| } |
| |
| /// Given the user provided list of items to document, expand all directories |
| /// to document out into specific files and add any dependent packages for |
| /// documentation if desired. |
| static List<Uri> _findLibrariesToDocument(List<String> args, |
| bool includeDependentPackages) { |
| if (includeDependentPackages) { |
| args.addAll(_allDependentPackageDirs(args.first)); |
| } |
| |
| var libraries = new List<Uri>(); |
| for (var arg in args) { |
| if (FileSystemEntity.typeSync(arg) == FileSystemEntityType.FILE) { |
| if (arg.endsWith('.dart')) { |
| var lib = new Uri.file(path.absolute(arg)); |
| libraries.add(lib); |
| logger.info('Added to libraries: $lib'); |
| } |
| } else { |
| libraries.addAll(_findFilesToDocumentInPackage(arg)); |
| } |
| } |
| return libraries; |
| } |
| |
| /// Given a package name, explore the directory and pull out all top level |
| /// library files in the "lib" directory to document. |
| static List<Uri> _findFilesToDocumentInPackage(String packageName) { |
| var libraries = []; |
| // To avoid anaylzing package files twice, only files with paths not |
| // containing '/packages' will be added. The only exception is if the file |
| // to analyze already has a '/package' in its path. |
| var files = listDir(packageName, recursive: true, listDir: _packageDirList) |
| .where((f) => f.endsWith('.dart') |
| && (!f.contains('${path.separator}packages') |
| || packageName.contains('${path.separator}packages'))).toList(); |
| |
| files.forEach((String lib) { |
| // Only include libraries at the top level of "lib" |
| if (path.basename(path.dirname(lib)) == 'lib') { |
| // Only add the file if it does not contain 'part of' |
| // TODO(janicejl): Remove when Issue(12406) is resolved. |
| var contents = new File(lib).readAsStringSync(); |
| if (!(contents.contains(new RegExp('\npart of ')) || |
| contents.startsWith(new RegExp('part of ')))) { |
| libraries.add(new Uri.file(path.normalize(path.absolute(lib)))); |
| logger.info('Added to libraries: $lib'); |
| } |
| } |
| }); |
| return libraries; |
| } |
| |
| /// If [dir] contains both a `lib` directory and a `pubspec.yaml` file treat |
| /// it like a package and only return the `lib` dir. |
| /// |
| /// This ensures that packages don't have non-`lib` content documented. |
| static List<FileSystemEntity> _packageDirList(Directory dir) { |
| var entities = dir.listSync(); |
| |
| var pubspec = entities |
| .firstWhere((e) => e is File && |
| path.basename(e.path) == 'pubspec.yaml', orElse: () => null); |
| |
| var libDir = entities |
| .firstWhere((e) => e is Directory && |
| path.basename(e.path) == 'lib', orElse: () => null); |
| |
| if (pubspec != null && libDir != null) { |
| return [libDir]; |
| } else { |
| return entities; |
| } |
| } |
| |
| /// All of the directories for our dependent packages |
| /// If this is not a package, return an empty list. |
| static List<String> _allDependentPackageDirs(String packageDirectory) { |
| var packageName = Library.packageNameFor(packageDirectory); |
| if (packageName == '') return []; |
| var dependentsJson = Process.runSync(_pubScript, ['list-package-dirs'], |
| workingDirectory: packageDirectory, runInShell: true); |
| if (dependentsJson.exitCode != 0) { |
| print(dependentsJson.stderr); |
| } |
| var dependents = JSON.decode(dependentsJson.stdout)['packages']; |
| return dependents.values.toList(); |
| } |
| |
| /// For all the libraries, return a list of the libraries that are part of |
| /// the SDK. |
| static List<Uri> _listSdk() { |
| var sdk = new List<Uri>(); |
| LIBRARIES.forEach((String name, LibraryInfo info) { |
| if (info.documented) { |
| sdk.add(Uri.parse('dart:$name')); |
| logger.info('Add to SDK: ${sdk.last}'); |
| } |
| }); |
| return sdk; |
| } |
| |
| /// Return true if this item and all of its owners are all visible. |
| static bool _isFullChainVisible(Indexable item) { |
| return _includePrivate || (!item.isPrivate && (item.owner != null ? |
| _isFullChainVisible(item.owner) : true)); |
| } |
| |
| /// Currently left public for testing purposes. :-/ |
| static void generateLibrary(dart2js_mirrors.Dart2JsLibraryMirror library) { |
| var result = new Library(library); |
| result._updateLibraryPackage(library); |
| logger.fine('Generated library for ${result.name}'); |
| } |
| } |
| |
| /// Convenience methods wrapped up in a class to pull down the docgen viewer for |
| /// a viewable website, and start up a server for viewing. |
| class _Viewer { |
| static String _dartdocViewerString = path.join(Directory.current.path, |
| 'dartdoc-viewer'); |
| static Directory _dartdocViewerDir = new Directory(_dartdocViewerString); |
| static Directory _topLevelTempDir; |
| static Directory _webDocsDir; |
| static bool movedViewerCode = false; |
| |
| static String _viewerCodePath; |
| |
| /* |
| * dartdoc-viewer currently has the web app code under a 'client' directory |
| * |
| * This is confusing for folks that want to clone and modify the code. |
| * It also includes a number of python files and other content related to |
| * app engine hosting that are not needed. |
| * |
| * This logic exists to support the current model and a (future) updated |
| * dartdoc-viewer repo where the 'client' content exists at the root of the |
| * project and the other content is removed. |
| */ |
| static String get viewerCodePath { |
| if(_viewerCodePath == null) { |
| var pubspecFileName = 'pubspec.yaml'; |
| |
| var thePath = _dartdocViewerDir.path; |
| |
| if(!FileSystemEntity.isFileSync(path.join(thePath, pubspecFileName))) { |
| thePath = path.join(thePath, 'client'); |
| if (!FileSystemEntity.isFileSync(path.join(thePath, pubspecFileName))) { |
| throw new StateError('Could not find a pubspec file'); |
| } |
| } |
| |
| _viewerCodePath = thePath; |
| } |
| return _viewerCodePath; |
| } |
| |
| /// If our dartdoc-viewer code is already checked out, move it to a temporary |
| /// directory outside of the package directory, so we don't try to process it |
| /// for documentation. |
| static void ensureMovedViewerCode() { |
| // TODO(efortuna): This will need to be modified to run on anyone's package |
| // outside of the checkout! |
| if (_dartdocViewerDir.existsSync()) { |
| _topLevelTempDir = new Directory( |
| _Generator._rootDirectory).createTempSync(); |
| _dartdocViewerDir.renameSync(_topLevelTempDir.path); |
| } |
| } |
| |
| /// Move the dartdoc-viewer code back into place for "webpage deployment." |
| static void addBackViewerCode() { |
| if (movedViewerCode) _dartdocViewerDir.renameSync(_dartdocViewerString); |
| } |
| |
| /// Serve up our generated documentation for viewing in a browser. |
| static void _clone() { |
| // If the viewer code is already there, then don't clone again. |
| if (_dartdocViewerDir.existsSync()) { |
| _moveDirectoryAndServe(); |
| } |
| else { |
| var processResult = Process.runSync('git', ['clone', '-b', 'master', |
| 'https://github.com/dart-lang/dartdoc-viewer.git'], |
| runInShell: true); |
| |
| if (processResult.exitCode == 0) { |
| /// Move the generated json/yaml docs directory to the dartdoc-viewer |
| /// directory, to run as a webpage. |
| var processResult = Process.runSync(_Generator._pubScript, |
| ['upgrade'], runInShell: true, |
| workingDirectory: viewerCodePath); |
| print('process output: ${processResult.stdout}'); |
| print('process stderr: ${processResult.stderr}'); |
| |
| var dir = new Directory(_Generator._outputDirectory == null? 'docs' : |
| _Generator._outputDirectory); |
| _webDocsDir = new Directory(path.join(viewerCodePath, 'web', 'docs')); |
| if (dir.existsSync()) { |
| // Move the docs folder to dartdoc-viewer/client/web/docs |
| dir.renameSync(_webDocsDir.path); |
| } |
| } else { |
| print('Error cloning git repository:'); |
| print('process output: ${processResult.stdout}'); |
| print('process stderr: ${processResult.stderr}'); |
| } |
| } |
| } |
| |
| /// Move the generated json/yaml docs directory to the dartdoc-viewer |
| /// directory, to run as a webpage. |
| static void _moveDirectoryAndServe() { |
| var processResult = Process.runSync(_Generator._pubScript, ['upgrade'], |
| runInShell: true, workingDirectory: path.join(_dartdocViewerDir.path, |
| 'client')); |
| print('process output: ${processResult.stdout}'); |
| print('process stderr: ${processResult.stderr}'); |
| |
| var dir = new Directory(_Generator._outputDirectory == null? 'docs' : |
| _Generator._outputDirectory); |
| var webDocsDir = new Directory(path.join(_dartdocViewerDir.path, 'client', |
| 'web', 'docs')); |
| if (dir.existsSync()) { |
| // Move the docs folder to dartdoc-viewer/client/web/docs |
| dir.renameSync(webDocsDir.path); |
| } |
| |
| if (webDocsDir.existsSync()) { |
| // Compile the code to JavaScript so we can run on any browser. |
| print('Compile app to JavaScript for viewing.'); |
| var processResult = Process.runSync(_Generator._dartBinary, |
| ['deploy.dart'], workingDirectory : path.join(_dartdocViewerDir.path, |
| 'client'), runInShell: true); |
| print('process output: ${processResult.stdout}'); |
| print('process stderr: ${processResult.stderr}'); |
| _runServer(); |
| } |
| } |
| |
| static void _compile() { |
| if (_webDocsDir.existsSync()) { |
| // Compile the code to JavaScript so we can run on any browser. |
| print('Compile app to JavaScript for viewing.'); |
| var processResult = Process.runSync(_Generator._dartBinary, |
| ['deploy.dart'], workingDirectory: viewerCodePath, runInShell: true); |
| print('process output: ${processResult.stdout}'); |
| print('process stderr: ${processResult.stderr}'); |
| var outputDir = path.join(viewerCodePath, 'out', 'web'); |
| print('Docs are available at $outputDir'); |
| } |
| } |
| |
| /// A simple HTTP server. Implemented here because this is part of the SDK, |
| /// so it shouldn't have any external dependencies. |
| static void _runServer() { |
| // Launch a server to serve out of the directory dartdoc-viewer/client/web. |
| HttpServer.bind(InternetAddress.ANY_IP_V6, 8080).then((HttpServer httpServer) { |
| print('Server launched. Navigate your browser to: ' |
| 'http://localhost:${httpServer.port}'); |
| httpServer.listen((HttpRequest request) { |
| var response = request.response; |
| var basePath = path.join(viewerCodePath, 'out', 'web'); |
| var requestPath = path.join(basePath, request.uri.path.substring(1)); |
| bool found = true; |
| var file = new File(requestPath); |
| if (file.existsSync()) { |
| // Set the correct header type. |
| if (requestPath.endsWith('.html')) { |
| response.headers.set('Content-Type', 'text/html'); |
| } else if (requestPath.endsWith('.js')) { |
| response.headers.set('Content-Type', 'application/javascript'); |
| } else if (requestPath.endsWith('.dart')) { |
| response.headers.set('Content-Type', 'application/dart'); |
| } else if (requestPath.endsWith('.css')) { |
| response.headers.set('Content-Type', 'text/css'); |
| } |
| } else { |
| if (requestPath == basePath) { |
| response.headers.set('Content-Type', 'text/html'); |
| file = new File(path.join(basePath, 'index.html')); |
| } else { |
| print('Path not found: $requestPath'); |
| found = false; |
| response.statusCode = HttpStatus.NOT_FOUND; |
| response.close(); |
| } |
| } |
| |
| if (found) { |
| // Serve up file contents. |
| file.openRead().pipe(response).catchError((e) { |
| print('HttpServer: error while closing the response stream $e'); |
| }); |
| } |
| }, |
| onError: (e) { |
| print('HttpServer: an error occured $e'); |
| }); |
| }); |
| } |
| } |
| |
| /// An item that is categorized in our mirrorToDocgen map, as a distinct, |
| /// searchable element. |
| /// |
| /// These are items that refer to concrete entities (a Class, for example, |
| /// but not a Type, which is a "pointer" to a class) that we wish to be |
| /// globally resolvable. This includes things such as class methods and |
| /// variables, but parameters for methods are not "Indexable" as we do not want |
| /// the user to be able to search for a method based on its parameter names! |
| /// The set of indexable items also includes Typedefs, since the user can refer |
| /// to them as concrete entities in a particular scope. |
| abstract class Indexable extends MirrorBased { |
| /// The dart:core library, which contains all types that are always available |
| /// without import. |
| static Library _coreLibrary; |
| |
| /// Set of libraries declared in the SDK, so libraries that can be accessed |
| /// when running dart by default. |
| static Iterable<LibraryMirror> _sdkLibraries; |
| |
| Library get _owningLibrary => owner._owningLibrary; |
| |
| String get qualifiedName => fileName; |
| final DeclarationMirror mirror; |
| final bool isPrivate; |
| /// The comment text pre-resolution. We keep this around because inherited |
| /// methods need to resolve links differently from the superclass. |
| String _unresolvedComment = ''; |
| |
| /// Index of all the dart2js mirrors examined to corresponding MirrorBased |
| /// docgen objects. |
| /// |
| /// Used for lookup because of the dart2js mirrors exports |
| /// issue. The second level map is indexed by owner docName for faster lookup. |
| /// Why two levels of lookup? Speed, man. Speed. |
| static Map<String, Map<String, Set<Indexable>>> _mirrorToDocgen = |
| new Map<String, Map<String, Set<Indexable>>>(); |
| |
| Indexable(DeclarationMirror mirror) |
| : this.mirror = mirror, |
| this.isPrivate = isHidden(mirror) { |
| |
| var map = _mirrorToDocgen[dart2js_util.qualifiedNameOf(this.mirror)]; |
| if (map == null) map = new Map<String, Set<Indexable>>(); |
| |
| var set = map[owner.docName]; |
| if (set == null) set = new Set<Indexable>(); |
| set.add(this); |
| map[owner.docName] = set; |
| _mirrorToDocgen[dart2js_util.qualifiedNameOf(this.mirror)] = map; |
| } |
| |
| static _initializeTopLevelLibraries(MirrorSystem mirrorSystem) { |
| _sdkLibraries = mirrorSystem.libraries.values.where( |
| (each) => each.uri.scheme == 'dart'); |
| _coreLibrary = new Library(_sdkLibraries.singleWhere((lib) => |
| lib.uri.toString().startsWith('dart:core'))); |
| } |
| |
| /// Returns this object's qualified name, but following the conventions |
| /// we're using in Dartdoc, which is that library names with dots in them |
| /// have them replaced with hyphens. |
| String get docName; |
| |
| /// Converts all [foo] references in comments to <a>libraryName.foo</a>. |
| markdown.Node fixReference(String name) { |
| // Attempt the look up the whole name up in the scope. |
| String elementName = findElementInScope(name); |
| if (elementName != null) { |
| return new markdown.Element.text('a', elementName); |
| } |
| return _fixComplexReference(name); |
| } |
| |
| /// Look for the specified name starting with the current member, and |
| /// progressively working outward to the current library scope. |
| String findElementInScope(String name) => |
| _findElementInScope(name, packagePrefix); |
| |
| /// The reference to this element based on where it is printed as a |
| /// documentation file and also the unique URL to refer to this item. |
| /// |
| /// The qualified name (for URL purposes) and the file name are the same, |
| /// of the form packageName/ClassName or packageName/ClassName.methodName. |
| /// This defines both the URL and the directory structure. |
| String get fileName => packagePrefix + ownerPrefix + name; |
| |
| /// The full docName of the owner element, appended with a '.' for this |
| /// object's name to be appended. |
| String get ownerPrefix => owner.docName != '' ? owner.docName + '.' : ''; |
| |
| /// The prefix String to refer to the package that this item is in, for URLs |
| /// and comment resolution. |
| /// |
| /// The prefix can be prepended to a qualified name to get a fully unique |
| /// name among all packages. |
| String get packagePrefix => ''; |
| |
| /// Documentation comment with converted markdown and all links resolved. |
| String _comment; |
| |
| /// Accessor to documentation comment with markdown converted to html and all |
| /// links resolved. |
| String get comment { |
| if (_comment != null) return _comment; |
| |
| _comment = _commentToHtml(); |
| if (_comment.isEmpty) { |
| _comment = _mdnComment(); |
| } |
| return _comment; |
| } |
| |
| set comment(x) => _comment = x; |
| |
| /// The simple name to refer to this item. |
| String get name => dart2js_util.nameOf(mirror); |
| |
| /// Accessor to the parent item that owns this item. |
| /// |
| /// "Owning" is defined as the object one scope-level above which this item |
| /// is defined. Ex: The owner for a top level class, would be its enclosing |
| /// library. The owner of a local variable in a method would be the enclosing |
| /// method. |
| Indexable get owner => new DummyMirror(mirror.owner); |
| |
| /// Generates MDN comments from database.json. |
| String _mdnComment(); |
| |
| /// The type of this member to be used in index.txt. |
| String get typeName => ''; |
| |
| /// Creates a [Map] with this [Indexable]'s name and a preview comment. |
| Map get previewMap { |
| var finalMap = { 'name' : name, 'qualifiedName' : qualifiedName }; |
| var preview = _preview; |
| if(preview != null) finalMap['preview'] = preview; |
| return finalMap; |
| } |
| |
| String get _preview { |
| if (comment != '') { |
| var index = comment.indexOf('</p>'); |
| return index > 0 ? |
| '${comment.substring(0, index)}</p>' : |
| '<p><i>Comment preview not available</i></p>'; |
| } |
| return null; |
| } |
| |
| /// Accessor to obtain the raw comment text for a given item, _without_ any |
| /// of the links resolved. |
| String get _commentText { |
| String commentText; |
| mirror.metadata.forEach((metadata) { |
| if (metadata is CommentInstanceMirror) { |
| CommentInstanceMirror comment = metadata; |
| if (comment.isDocComment) { |
| if (commentText == null) { |
| commentText = comment.trimmedText; |
| } else { |
| commentText = '$commentText\n${comment.trimmedText}'; |
| } |
| } |
| } |
| }); |
| return commentText; |
| } |
| |
| /// Returns any documentation comments associated with a mirror with |
| /// simple markdown converted to html. |
| /// |
| /// By default we resolve any comment references within our own scope. |
| /// However, if a method is inherited, we want the inherited comments, but |
| /// links to the subclasses's version of the methods. |
| String _commentToHtml([Indexable resolvingScope]) { |
| if (resolvingScope == null) resolvingScope = this; |
| var commentText = _commentText; |
| _unresolvedComment = commentText; |
| |
| var linkResolver = (name) => resolvingScope.fixReference(name); |
| commentText = commentText == null ? '' : |
| markdown.markdownToHtml(commentText.trim(), linkResolver: linkResolver, |
| inlineSyntaxes: _MARKDOWN_SYNTAXES); |
| return commentText; |
| } |
| |
| /// Returns a map of [Variable] objects constructed from [mirrorMap]. |
| /// The optional parameter [containingLibrary] is contains data for variables |
| /// defined at the top level of a library (potentially for exporting |
| /// purposes). |
| Map<String, Variable> _createVariables(Iterable<VariableMirror> mirrors, |
| Indexable owner) { |
| var data = {}; |
| // TODO(janicejl): When map to map feature is created, replace the below |
| // with a filter. Issue(#9590). |
| mirrors.forEach((VariableMirror mirror) { |
| if (_Generator._includePrivate || !isHidden(mirror)) { |
| var mirrorName = dart2js_util.nameOf(mirror); |
| data[mirrorName] = new Variable(mirrorName, mirror, owner); |
| } |
| }); |
| return data; |
| } |
| |
| /// Returns a map of [Method] objects constructed from [mirrorMap]. |
| /// The optional parameter [containingLibrary] is contains data for variables |
| /// defined at the top level of a library (potentially for exporting |
| /// purposes). |
| Map<String, Method> _createMethods(Iterable<MethodMirror> mirrors, |
| Indexable owner) { |
| var group = new Map<String, Method>(); |
| mirrors.forEach((MethodMirror mirror) { |
| if (_Generator._includePrivate || !mirror.isPrivate) { |
| group[dart2js_util.nameOf(mirror)] = new Method(mirror, owner); |
| } |
| }); |
| return group; |
| } |
| |
| /// Returns a map of [Parameter] objects constructed from [mirrorList]. |
| Map<String, Parameter> _createParameters(List<ParameterMirror> mirrorList, |
| Indexable owner) { |
| var data = {}; |
| mirrorList.forEach((ParameterMirror mirror) { |
| data[dart2js_util.nameOf(mirror)] = |
| new Parameter(mirror, owner._owningLibrary); |
| }); |
| return data; |
| } |
| |
| /// Returns a map of [Generic] objects constructed from the class mirror. |
| Map<String, Generic> _createGenerics(TypeMirror mirror) { |
| return new Map.fromIterable(mirror.typeVariables, |
| key: (e) => dart2js_util.nameOf(e), |
| value: (e) => new Generic(e)); |
| } |
| |
| /// Return an informative [Object.toString] for debugging. |
| String toString() => "${super.toString()}(${name.toString()})"; |
| |
| /// Return a map representation of this type. |
| Map toMap(); |
| |
| |
| |
| ////// Top level resolution functions |
| /// Converts all [foo] references in comments to <a>libraryName.foo</a>. |
| static markdown.Node globalFixReference(String name) { |
| // Attempt the look up the whole name up in the scope. |
| String elementName = _findElementInScope(name, ''); |
| if (elementName != null) { |
| return new markdown.Element.text('a', elementName); |
| } |
| return _fixComplexReference(name); |
| } |
| |
| /// This is a more complex reference. Try to break up if its of the form A<B> |
| /// where A is an alphanumeric string and B is an A, a list of B ("B, B, B"), |
| /// or of the form A<B>. Note: unlike other the other markdown-style links, |
| /// all text inside the square brackets is treated as part of the link (aka |
| /// the * is interpreted literally as a *, not as a indicator for bold <em>. |
| /// |
| /// Example: [foo<_bar_>] will produce |
| /// <a>resolvedFoo</a><<a>resolved_bar_</a>> rather than an italicized |
| /// version of resolvedBar. |
| static markdown.Node _fixComplexReference(String name) { |
| // Parse into multiple elements we can try to resolve. |
| var tokens = tokenizeComplexReference(name); |
| |
| // Produce an html representation of our elements. Group unresolved and |
| // plain text are grouped into "link" elements so they display as code. |
| final textElements = [' ', ',', '>', LESS_THAN]; |
| var accumulatedHtml = ''; |
| |
| for (var token in tokens) { |
| bool added = false; |
| if (!textElements.contains(token)) { |
| String elementName = _findElementInScope(token, ''); |
| if (elementName != null) { |
| accumulatedHtml += markdown.renderToHtml([new markdown.Element.text( |
| 'a', elementName)]); |
| added = true; |
| } |
| } |
| if (!added) { |
| accumulatedHtml += token; |
| } |
| } |
| return new markdown.Text(accumulatedHtml); |
| } |
| |
| static String _findElementInScope(String name, String packagePrefix) { |
| var lookupFunc = determineLookupFunc(name); |
| // Look in the dart core library scope. |
| var coreScope = _coreLibrary == null? null : |
| lookupFunc(_coreLibrary.mirror, name); |
| if (coreScope != null) return packagePrefix + _coreLibrary.docName; |
| |
| // If it's a reference that starts with a another library name, then it |
| // looks for a match of that library name in the other sdk libraries. |
| if(name.contains('.')) { |
| var index = name.indexOf('.'); |
| var libraryName = name.substring(0, index); |
| var remainingName = name.substring(index + 1); |
| foundLibraryName(library) => library.uri.pathSegments[0] == libraryName; |
| |
| if (_sdkLibraries.any(foundLibraryName)) { |
| var library = _sdkLibraries.singleWhere(foundLibraryName); |
| // Look to see if it's a fully qualified library name. |
| var scope = determineLookupFunc(remainingName)(library, remainingName); |
| if (scope != null) { |
| var result = getDocgenObject(scope); |
| if (result is DummyMirror) { |
| return packagePrefix + result.docName; |
| } else { |
| return result.packagePrefix + result.docName; |
| } |
| } |
| } |
| } |
| return null; |
| } |
| |
| /// Expand the method map [mapToExpand] into a more detailed map that |
| /// separates out setters, getters, constructors, operators, and methods. |
| Map _expandMethodMap(Map<String, Method> mapToExpand) => { |
| 'setters': recurseMap(filterMap(mapToExpand, |
| (key, val) => val.mirror.isSetter)), |
| 'getters': recurseMap(filterMap(mapToExpand, |
| (key, val) => val.mirror.isGetter)), |
| 'constructors': recurseMap(filterMap(mapToExpand, |
| (key, val) => val.mirror.isConstructor)), |
| 'operators': recurseMap(filterMap(mapToExpand, |
| (key, val) => val.mirror.isOperator)), |
| 'methods': recurseMap(filterMap(mapToExpand, |
| (key, val) => val.mirror.isRegularMethod && !val.mirror.isOperator)) |
| }; |
| |
| /// Accessor to determine if this item and all of its owners are visible. |
| bool get _isVisible => _Generator._isFullChainVisible(this); |
| |
| /// Given a Dart2jsMirror, find the corresponding Docgen [MirrorBased] object. |
| /// |
| /// We have this global lookup function to avoid re-implementing looking up |
| /// the scoping rules for comment resolution here (it is currently done in |
| /// mirrors). If no corresponding MirrorBased object is found, we return a |
| /// [DummyMirror] that simply returns the original mirror's qualifiedName |
| /// while behaving like a MirrorBased object. |
| static Indexable getDocgenObject(DeclarationMirror mirror, |
| [Indexable owner]) { |
| Map<String, Set<Indexable>> docgenObj = |
| _mirrorToDocgen[dart2js_util.qualifiedNameOf(mirror)]; |
| if (docgenObj == null) { |
| return new DummyMirror(mirror, owner); |
| } |
| |
| var setToExamine = new Set(); |
| if (owner != null) { |
| var firstSet = docgenObj[owner.docName]; |
| if (firstSet != null) setToExamine.addAll(firstSet); |
| if (_coreLibrary != null && |
| docgenObj[_coreLibrary.docName] != null) { |
| setToExamine.addAll(docgenObj[_coreLibrary.docName]); |
| } |
| } else { |
| for (var value in docgenObj.values) { |
| setToExamine.addAll(value); |
| } |
| } |
| |
| Set<Indexable> results = new Set<Indexable>(); |
| for(Indexable indexable in setToExamine) { |
| if (indexable.mirror.qualifiedName == mirror.qualifiedName && |
| indexable._isValidMirror(mirror)) { |
| results.add(indexable); |
| } |
| } |
| |
| if (results.length > 0) { |
| // This might occur if we didn't specify an "owner." |
| return results.first; |
| } |
| return new DummyMirror(mirror, owner); |
| } |
| |
| /// Returns true if [mirror] is the correct type of mirror that this Docgen |
| /// object wraps. (Workaround for the fact that Types are not first class.) |
| bool _isValidMirror(DeclarationMirror mirror); |
| } |
| |
| /// A class containing contents of a Dart library. |
| class Library extends Indexable { |
| final Map<String, Class> classes = {}; |
| final Map<String, Typedef> typedefs = {}; |
| final Map<String, Class> errors = {}; |
| |
| /// Top-level variables in the library. |
| Map<String, Variable> variables; |
| |
| /// Top-level functions in the library. |
| Map<String, Method> functions; |
| |
| String packageName = ''; |
| bool _hasBeenCheckedForPackage = false; |
| String packageIntro; |
| |
| Library get _owningLibrary => this; |
| |
| /// Returns the [Library] for the given [mirror] if it has already been |
| /// created, else creates it. |
| factory Library(LibraryMirror mirror) { |
| var library = Indexable.getDocgenObject(mirror); |
| if (library is DummyMirror) { |
| library = new Library._(mirror); |
| } |
| return library; |
| } |
| |
| Library._(LibraryMirror libraryMirror) : super(libraryMirror) { |
| var exported = _calcExportedItems(libraryMirror); |
| var exportedClasses = _addAll(exported['classes'], |
| dart2js_util.typesOf(libraryMirror.declarations)); |
| _updateLibraryPackage(mirror); |
| exportedClasses.forEach((String mirrorName, TypeMirror mirror) { |
| if (mirror is TypedefMirror) { |
| // This is actually a Dart2jsTypedefMirror, and it does define value, |
| // but we don't have visibility to that type. |
| if (_Generator._includePrivate || !mirror.isPrivate) { |
| typedefs[dart2js_util.nameOf(mirror)] = new Typedef(mirror, this); |
| } |
| } else if (mirror is ClassMirror) { |
| var clazz = new Class(mirror, this); |
| |
| if (clazz.isError()) { |
| errors[dart2js_util.nameOf(mirror)] = clazz; |
| } else { |
| classes[dart2js_util.nameOf(mirror)] = clazz; |
| } |
| } else { |
| throw new ArgumentError( |
| '${dart2js_util.nameOf(mirror)} - no class type match. '); |
| } |
| }); |
| this.functions = _createMethods(_addAll(exported['methods'], |
| libraryMirror.declarations.values.where( |
| (mirror) => mirror is MethodMirror)).values, this); |
| this.variables = _createVariables(_addAll(exported['variables'], |
| dart2js_util.variablesOf(libraryMirror.declarations)).values, this); |
| } |
| |
| /// Look for the specified name starting with the current member, and |
| /// progressively working outward to the current library scope. |
| String findElementInScope(String name) { |
| var lookupFunc = determineLookupFunc(name); |
| var libraryScope = lookupFunc(mirror, name); |
| if (libraryScope != null) { |
| var result = Indexable.getDocgenObject(libraryScope, this); |
| if (result is DummyMirror) return packagePrefix + result.docName; |
| return result.packagePrefix + result.docName; |
| } |
| return super.findElementInScope(name); |
| } |
| |
| String _mdnComment() => ''; |
| |
| /// Helper that maps [mirrors] to their simple name in map. |
| static Map _addAll(Map map, Iterable<DeclarationMirror> mirrors) { |
| for (var mirror in mirrors) { |
| map[dart2js_util.nameOf(mirror)] = mirror; |
| } |
| return map; |
| } |
| |
| /// For a library's [mirror], determine the name of the package (if any) we |
| /// believe it came from (because of its file URI). |
| /// |
| /// If no package could be determined, we return an empty string. |
| void _updateLibraryPackage(LibraryMirror mirror) { |
| if (mirror == null) return; |
| if (_hasBeenCheckedForPackage) return; |
| _hasBeenCheckedForPackage = true; |
| if (mirror.uri.scheme != 'file') return; |
| packageName = _packageName(mirror); |
| // Associate the package readme with all the libraries. This is a bit |
| // wasteful, but easier than trying to figure out which partial match |
| // is best. |
| packageIntro = _packageIntro(_getPackageDirectory(mirror)); |
| } |
| |
| String _packageIntro(packageDir) { |
| if (packageDir == null) return null; |
| var dir = new Directory(packageDir); |
| var files = dir.listSync(); |
| var readmes = files.where((FileSystemEntity each) => (each is File && |
| each.path.substring(packageDir.length + 1, each.path.length) |
| .startsWith('README'))).toList(); |
| if (readmes.isEmpty) return ''; |
| // If there are multiples, pick the shortest name. |
| readmes.sort((a, b) => a.path.length.compareTo(b.path.length)); |
| var readme = readmes.first; |
| var linkResolver = (name) => Indexable.globalFixReference(name); |
| var contents = markdown.markdownToHtml(readme |
| .readAsStringSync(), linkResolver: linkResolver, |
| inlineSyntaxes: _MARKDOWN_SYNTAXES); |
| return contents; |
| } |
| |
| /// Given a LibraryMirror that is a library, return the name of the directory |
| /// holding the package information for that library. If the library is not |
| /// part of a package, return null. |
| static String _getPackageDirectory(LibraryMirror mirror) { |
| var file = mirror.uri.toFilePath(); |
| // Any file that's in a package will be in a directory of the form |
| // packagename/lib/.../filename.dart, so we know that a possible |
| // package directory is at least in the directory above the one containing |
| // [file] |
| var directoryAbove = path.dirname(path.dirname(file)); |
| var possiblePackage = _packageDirectoryFor(directoryAbove); |
| // We only want components that are somewhere underneath the lib directory. |
| var subPath = path.relative(file, from: possiblePackage); |
| var subPathComponents = path.split(subPath); |
| if (subPathComponents.isNotEmpty && subPathComponents.first == 'lib') { |
| return possiblePackage; |
| } else { |
| return null; |
| } |
| } |
| |
| /// Read a pubspec and return the library name given a [LibraryMirror]. |
| static String _packageName(LibraryMirror mirror) { |
| if (mirror.uri.scheme != 'file') return ''; |
| var rootdir = _getPackageDirectory(mirror); |
| if (rootdir == null) return ''; |
| return packageNameFor(rootdir); |
| } |
| |
| /// Recursively walk up from directory name looking for a pubspec. Return |
| /// the directory that contains it, or null if none is found. |
| static String _packageDirectoryFor(String directoryName) { |
| var dir = directoryName; |
| while (!_pubspecFor(dir).existsSync()) { |
| var newDir = path.dirname(dir); |
| if (newDir == dir) return null; |
| dir = newDir; |
| } |
| return dir; |
| } |
| |
| static File _pubspecFor(String directoryName) => |
| new File(path.join(directoryName, 'pubspec.yaml')); |
| |
| /// Read a pubspec and return the library name, given a directory |
| static String packageNameFor(String directoryName) { |
| var pubspecName = path.join(directoryName, 'pubspec.yaml'); |
| File pubspec = new File(pubspecName); |
| if (!pubspec.existsSync()) return ''; |
| var contents = pubspec.readAsStringSync(); |
| var spec = loadYaml(contents); |
| return spec["name"]; |
| } |
| |
| String get packagePrefix => packageName == null || packageName.isEmpty ? |
| '' : '$packageName/'; |
| |
| Map get previewMap { |
| var basic = super.previewMap; |
| basic['packageName'] = packageName; |
| if (packageIntro != null) { |
| basic['packageIntro'] = packageIntro; |
| } |
| return basic; |
| } |
| |
| String get name => docName; |
| |
| String get docName { |
| return dart2js_util.qualifiedNameOf(mirror).replaceAll('.','-'); |
| } |
| |
| /// For the given library determine what items (if any) are exported. |
| /// |
| /// Returns a Map with three keys: "classes", "methods", and "variables" the |
| /// values of which point to a map of exported name identifiers with values |
| /// corresponding to the actual DeclarationMirror. |
| Map<String, Map<String, DeclarationMirror>> _calcExportedItems( |
| LibrarySourceMirror library) { |
| var exports = {}; |
| exports['classes'] = {}; |
| exports['methods'] = {}; |
| exports['variables'] = {}; |
| |
| // Determine the classes, variables and methods that are exported for a |
| // specific dependency. |
| void _populateExports(LibraryDependencyMirror export, bool showExport) { |
| if (!showExport) { |
| // Add all items, and then remove the hidden ones. |
| // Ex: "export foo hide bar" |
| _addAll(exports['classes'], |
| dart2js_util.typesOf(export.targetLibrary.declarations)); |
| _addAll(exports['methods'], |
| export.targetLibrary.declarations.values.where( |
| (mirror) => mirror is MethodMirror)); |
| _addAll(exports['variables'], |
| dart2js_util.variablesOf(export.targetLibrary.declarations)); |
| } |
| for (CombinatorMirror combinator in export.combinators) { |
| for (String identifier in combinator.identifiers) { |
| DeclarationMirror declaration = |
| export.targetLibrary.lookupInScope(identifier); |
| if (declaration == null) { |
| // Technically this should be a bug, but some of our packages |
| // (such as the polymer package) are curently broken in this |
| // way, so we just produce a warning. |
| print('Warning identifier $identifier not found in library ' |
| '${dart2js_util.qualifiedNameOf(export.targetLibrary)}'); |
| } else { |
| var subMap = exports['classes']; |
| if (declaration is MethodMirror) { |
| subMap = exports['methods']; |
| } else if (declaration is VariableMirror) { |
| subMap = exports['variables']; |
| } |
| if (showExport) { |
| subMap[identifier] = declaration; |
| } else { |
| subMap.remove(identifier); |
| } |
| } |
| } |
| } |
| } |
| |
| Iterable<LibraryDependencyMirror> exportList = |
| library.libraryDependencies.where((lib) => lib.isExport); |
| for (LibraryDependencyMirror export in exportList) { |
| // If there is a show in the export, add only the show items to the |
| // library. Ex: "export foo show bar" |
| // Otherwise, add all items, and then remove the hidden ones. |
| // Ex: "export foo hide bar" |
| _populateExports(export, |
| export.combinators.any((combinator) => combinator.isShow)); |
| } |
| return exports; |
| } |
| |
| /// Checks if the given name is a key for any of the Class Maps. |
| bool containsKey(String name) => |
| classes.containsKey(name) || errors.containsKey(name); |
| |
| /// Generates a map describing the [Library] object. |
| Map toMap() => { |
| 'name': name, |
| 'qualifiedName': qualifiedName, |
| 'comment': comment, |
| 'variables': recurseMap(variables), |
| 'functions': _expandMethodMap(functions), |
| 'classes': { |
| 'class': classes.values.where((c) => c._isVisible) |
| .map((e) => e.previewMap).toList(), |
| 'typedef': recurseMap(typedefs), |
| 'error': errors.values.where((e) => e._isVisible) |
| .map((e) => e.previewMap).toList() |
| }, |
| 'packageName': packageName, |
| 'packageIntro' : packageIntro |
| }; |
| |
| String get typeName => 'library'; |
| |
| bool _isValidMirror(DeclarationMirror mirror) => mirror is LibraryMirror; |
| } |
| |
| abstract class OwnedIndexable extends Indexable { |
| /// The object one scope-level above which this item is defined. |
| /// |
| /// Ex: The owner for a top level class, would be its enclosing library. |
| /// The owner of a local variable in a method would be the enclosing method. |
| Indexable owner; |
| |
| /// List of the meta annotations on this item. |
| List<Annotation> annotations; |
| |
| /// Returns this object's qualified name, but following the conventions |
| /// we're using in Dartdoc, which is that library names with dots in them |
| /// have them replaced with hyphens. |
| String get docName => owner.docName + '.' + dart2js_util.nameOf(mirror); |
| |
| OwnedIndexable(DeclarationMirror mirror, this.owner) : super(mirror); |
| |
| /// Generates MDN comments from database.json. |
| String _mdnComment() { |
| var domAnnotation = this.annotations.firstWhere( |
| (e) => e.mirror.qualifiedName == #metadata.DomName, |
| orElse: () => null); |
| if (domAnnotation == null) return ''; |
| var domName = domAnnotation.parameters.single; |
| |
| return mdnComment(_Generator._rootDirectory, _Generator.logger, domName); |
| } |
| |
| String get packagePrefix => owner.packagePrefix; |
| } |
| |
| /// A class containing contents of a Dart class. |
| class Class extends OwnedIndexable implements Comparable { |
| |
| /// List of the names of interfaces that this class implements. |
| List<Class> interfaces = []; |
| |
| /// Names of classes that extends or implements this class. |
| Set<Class> subclasses = new Set<Class>(); |
| |
| /// Top-level variables in the class. |
| Map<String, Variable> variables; |
| |
| /// Inherited variables in the class. |
| Map<String, Variable> inheritedVariables; |
| |
| /// Methods in the class. |
| Map<String, Method> methods; |
| |
| Map<String, Method> inheritedMethods; |
| |
| /// Generic infomation about the class. |
| Map<String, Generic> generics; |
| |
| Class superclass; |
| bool isAbstract; |
| |
| /// Make sure that we don't check for inherited comments more than once. |
| bool _commentsEnsured = false; |
| |
| /// Returns the [Class] for the given [mirror] if it has already been created, |
| /// else creates it. |
| factory Class(ClassMirror mirror, Library owner) { |
| var clazz = Indexable.getDocgenObject(mirror, owner); |
| if (clazz is DummyMirror) { |
| clazz = new Class._(mirror, owner); |
| } |
| return clazz; |
| } |
| |
| /// Called when we are constructing a superclass or interface class, but it |
| /// is not known if it belongs to the same owner as the original class. In |
| /// this case, we create an object whose owner is what the original mirror |
| /// says it is. |
| factory Class._possiblyDifferentOwner(ClassMirror mirror, |
| Library originalOwner) { |
| if (mirror.owner is LibraryMirror) { |
| var realOwner = Indexable.getDocgenObject(mirror.owner); |
| if (realOwner is Library) { |
| return new Class(mirror, realOwner); |
| } else { |
| return new Class(mirror, originalOwner); |
| } |
| } else { |
| return new Class(mirror, originalOwner); |
| } |
| } |
| |
| Class._(ClassSourceMirror classMirror, Indexable owner) : |
| super(classMirror, owner) { |
| inheritedVariables = {}; |
| |
| // The reason we do this madness is the superclass and interface owners may |
| // not be this class's owner!! Example: BaseClient in http pkg. |
| var superinterfaces = classMirror.superinterfaces.map( |
| (interface) => new Class._possiblyDifferentOwner(interface, owner)); |
| this.superclass = classMirror.superclass == null? null : |
| new Class._possiblyDifferentOwner(classMirror.superclass, owner); |
| |
| interfaces = superinterfaces.toList(); |
| variables = _createVariables( |
| dart2js_util.variablesOf(classMirror.declarations), this); |
| methods = _createMethods(classMirror.declarations.values.where( |
| (mirror) => mirror is MethodMirror), this); |
| annotations = _createAnnotations(classMirror, owner._owningLibrary); |
| generics = _createGenerics(classMirror); |
| isAbstract = classMirror.isAbstract; |
| inheritedMethods = new Map<String, Method>(); |
| |
| // Tell superclass that you are a subclass, unless you are not |
| // visible or an intermediary mixin class. |
| if (!classMirror.isNameSynthetic && _isVisible && superclass != null) { |
| superclass.addSubclass(this); |
| } |
| |
| if (this.superclass != null) addInherited(superclass); |
| interfaces.forEach((interface) => addInherited(interface)); |
| } |
| |
| String _lookupInClassAndSuperclasses(String name) { |
| var lookupFunc = determineLookupFunc(name); |
| var classScope = this; |
| while (classScope != null) { |
| var classFunc = lookupFunc(classScope.mirror, name); |
| if (classFunc != null) { |
| return packagePrefix + Indexable.getDocgenObject(classFunc, owner).docName; |
| } |
| classScope = classScope.superclass; |
| } |
| return null; |
| } |
| |
| /// Look for the specified name starting with the current member, and |
| /// progressively working outward to the current library scope. |
| String findElementInScope(String name) { |
| var lookupFunc = determineLookupFunc(name); |
| var result = _lookupInClassAndSuperclasses(name); |
| if (result != null) { |
| return result; |
| } |
| result = owner.findElementInScope(name); |
| return result == null ? super.findElementInScope(name) : result; |
| } |
| |
| String get typeName => 'class'; |
| |
| /// Add all inherited variables and methods from the provided superclass. |
| /// If [_includePrivate] is true, it also adds the variables and methods from |
| /// the superclass. |
| void addInherited(Class superclass) { |
| inheritedVariables.addAll(superclass.inheritedVariables); |
| inheritedVariables.addAll(_allButStatics(superclass.variables)); |
| addInheritedMethod(superclass, this); |
| } |
| |
| /** [newParent] refers to the actual class is currently using these methods. |
| * which may be different because with the mirror system, we only point to the |
| * original canonical superclasse's method. |
| */ |
| void addInheritedMethod(Class parent, Class newParent) { |
| parent.inheritedMethods.forEach((name, method) { |
| if(!method.mirror.isConstructor){ |
| inheritedMethods[name] = new Method(method.mirror, newParent, method); |
| }} |
| ); |
| _allButStatics(parent.methods).forEach((name, method) { |
| if (!method.mirror.isConstructor) { |
| inheritedMethods[name] = new Method(method.mirror, newParent, method); |
| }} |
| ); |
| } |
| |
| /// Remove statics from the map of inherited items before adding them. |
| Map _allButStatics(Map items) { |
| var result = {}; |
| items.forEach((name, item) { |
| if (!item.isStatic) { |
| result[name] = item; |
| } |
| }); |
| return result; |
| } |
| |
| /// Add the subclass to the class. |
| /// |
| /// If [this] is private (or an intermediary mixin class), it will add the |
| /// subclass to the list of subclasses in the superclasses. |
| void addSubclass(Class subclass) { |
| if (docName == 'dart-core.Object') return; |
| |
| if (!_Generator._includePrivate && isPrivate || mirror.isNameSynthetic) { |
| if (superclass != null) superclass.addSubclass(subclass); |
| interfaces.forEach((interface) { |
| interface.addSubclass(subclass); |
| }); |
| } else { |
| subclasses.add(subclass); |
| } |
| } |
| |
| /// Check if this [Class] is an error or exception. |
| bool isError() { |
| if (qualifiedName == 'dart-core.Error' || |
| qualifiedName == 'dart-core.Exception') |
| return true; |
| for (var interface in interfaces) { |
| if (interface.isError()) return true; |
| } |
| if (superclass == null) return false; |
| return superclass.isError(); |
| } |
| |
| /// Makes sure that all methods with inherited equivalents have comments. |
| void ensureComments() { |
| if (_commentsEnsured) return; |
| _commentsEnsured = true; |
| if (superclass != null) superclass.ensureComments(); |
| inheritedMethods.forEach((qualifiedName, inheritedMethod) { |
| var method = methods[qualifiedName]; |
| if (method != null) { |
| // if we have overwritten this method in this class, we still provide |
| // the opportunity to inherit the comments. |
| method.ensureCommentFor(inheritedMethod); |
| } |
| }); |
| // we need to populate the comments for all methods. so that the subclasses |
| // can get for their inherited versions the comments. |
| methods.forEach((qualifiedName, method) { |
| if (!method.mirror.isConstructor) method.ensureCommentFor(method); |
| }); |
| } |
| |
| /// If a class extends a private superclass, find the closest public |
| /// superclass of the private superclass. |
| String validSuperclass() { |
| if (superclass == null) return 'dart-core.Object'; |
| if (superclass._isVisible) return superclass.qualifiedName; |
| return superclass.validSuperclass(); |
| } |
| |
| /// Generates a map describing the [Class] object. |
| Map toMap() => { |
| 'name': name, |
| 'qualifiedName': qualifiedName, |
| 'comment': comment, |
| 'isAbstract' : isAbstract, |
| 'superclass': validSuperclass(), |
| 'implements': interfaces.where((i) => i._isVisible) |
| .map((e) => e.qualifiedName).toList(), |
| 'subclass': (subclasses.toList()..sort()) |
| .map((x) => x.qualifiedName).toList(), |
| 'variables': recurseMap(variables), |
| 'inheritedVariables': recurseMap(inheritedVariables), |
| 'methods': _expandMethodMap(methods), |
| 'inheritedMethods': _expandMethodMap(inheritedMethods), |
| 'annotations': annotations.map((a) => a.toMap()).toList(), |
| 'generics': recurseMap(generics) |
| }; |
| |
| int compareTo(aClass) => name.compareTo(aClass.name); |
| |
| bool _isValidMirror(DeclarationMirror mirror) => mirror is ClassMirror; |
| } |
| |
| class Typedef extends OwnedIndexable { |
| String returnType; |
| |
| Map<String, Parameter> parameters; |
| |
| /// Generic information about the typedef. |
| Map<String, Generic> generics; |
| |
| /// Returns the [Library] for the given [mirror] if it has already been |
| /// created, else creates it. |
| factory Typedef(TypedefMirror mirror, Library owningLibrary) { |
| var aTypedef = Indexable.getDocgenObject(mirror, owningLibrary); |
| if (aTypedef is DummyMirror) { |
| aTypedef = new Typedef._(mirror, owningLibrary); |
| } |
| return aTypedef; |
| } |
| |
| Typedef._(TypedefMirror mirror, Library owningLibrary) : |
| super(mirror, owningLibrary) { |
| returnType = Indexable.getDocgenObject(mirror.referent.returnType).docName; |
| generics = _createGenerics(mirror); |
| parameters = _createParameters(mirror.referent.parameters, owningLibrary); |
| annotations = _createAnnotations(mirror, owningLibrary); |
| } |
| |
| Map toMap() { |
| var map = { |
| 'name': name, |
| 'qualifiedName': qualifiedName, |
| 'comment': comment, |
| 'return': returnType, |
| 'parameters': recurseMap(parameters), |
| 'annotations': annotations.map((a) => a.toMap()).toList(), |
| 'generics': recurseMap(generics) |
| }; |
| |
| // Typedef is displayed on the library page as a class, so a preview is |
| // added manually |
| var preview = _preview; |
| if(preview != null) map['preview'] = preview; |
| |
| return map; |
| } |
| |
| markdown.Node fixReference(String name) => null; |
| |
| String get typeName => 'typedef'; |
| |
| bool _isValidMirror(DeclarationMirror mirror) => mirror is TypedefMirror; |
| } |
| |
| /// A class containing properties of a Dart variable. |
| class Variable extends OwnedIndexable { |
| |
| bool isFinal; |
| bool isStatic; |
| bool isConst; |
| Type type; |
| String _variableName; |
| |
| factory Variable(String variableName, VariableMirror mirror, |
| Indexable owner) { |
| var variable = Indexable.getDocgenObject(mirror); |
| if (variable is DummyMirror) { |
| return new Variable._(variableName, mirror, owner); |
| } |
| return variable; |
| } |
| |
| Variable._(this._variableName, VariableMirror mirror, Indexable owner) : |
| super(mirror, owner) { |
| isFinal = mirror.isFinal; |
| isStatic = mirror.isStatic; |
| isConst = mirror.isConst; |
| type = new Type(mirror.type, owner._owningLibrary); |
| annotations = _createAnnotations(mirror, owner._owningLibrary); |
| } |
| |
| String get name => _variableName; |
| |
| /// Generates a map describing the [Variable] object. |
| Map toMap() => { |
| 'name': name, |
| 'qualifiedName': qualifiedName, |
| 'comment': comment, |
| 'final': isFinal, |
| 'static': isStatic, |
| 'constant': isConst, |
| 'type': new List.filled(1, type.toMap()), |
| 'annotations': annotations.map((a) => a.toMap()).toList() |
| }; |
| |
| String get typeName => 'property'; |
| |
| get comment { |
| if (_comment != null) return _comment; |
| if (owner is Class) { |
| (owner as Class).ensureComments(); |
| } |
| return super.comment; |
| } |
| |
| String findElementInScope(String name) { |
| var lookupFunc = determineLookupFunc(name); |
| var result = lookupFunc(mirror, name); |
| if (result != null) { |
| result = Indexable.getDocgenObject(result); |
| if (result is DummyMirror) return packagePrefix + result.docName; |
| return result.packagePrefix + result.docName; |
| } |
| |
| if (owner != null) { |
| var result = owner.findElementInScope(name); |
| if (result != null) { |
| return result; |
| } |
| } |
| return super.findElementInScope(name); |
| } |
| |
| bool _isValidMirror(DeclarationMirror mirror) => mirror is VariableMirror; |
| } |
| |
| /// A class containing properties of a Dart method. |
| class Method extends OwnedIndexable { |
| |
| /// Parameters for this method. |
| Map<String, Parameter> parameters; |
| |
| bool isStatic; |
| bool isAbstract; |
| bool isConst; |
| Type returnType; |
| Method methodInheritedFrom; |
| |
| /// Qualified name to state where the comment is inherited from. |
| String commentInheritedFrom = ""; |
| |
| factory Method(MethodMirror mirror, Indexable owner, |
| [Method methodInheritedFrom]) { |
| var method = Indexable.getDocgenObject(mirror, owner); |
| if (method is DummyMirror) { |
| method = new Method._(mirror, owner, methodInheritedFrom); |
| } |
| return method; |
| } |
| |
| Method._(MethodMirror mirror, Indexable owner, this.methodInheritedFrom) |
| : super(mirror, owner) { |
| isStatic = mirror.isStatic; |
| isAbstract = mirror.isAbstract; |
| isConst = mirror.isConstConstructor; |
| returnType = new Type(mirror.returnType, owner._owningLibrary); |
| parameters = _createParameters(mirror.parameters, owner); |
| annotations = _createAnnotations(mirror, owner._owningLibrary); |
| } |
| |
| Method get originallyInheritedFrom => methodInheritedFrom == null ? |
| this : methodInheritedFrom.originallyInheritedFrom; |
| |
| /// Look for the specified name starting with the current member, and |
| /// progressively working outward to the current library scope. |
| String findElementInScope(String name) { |
| var lookupFunc = determineLookupFunc(name); |
| |
| var memberScope = lookupFunc(this.mirror, name); |
| if (memberScope != null) { |
| // do we check for a dummy mirror returned here and look up with an owner |
| // higher ooooor in getDocgenObject do we include more things in our |
| // lookup |
| var result = Indexable.getDocgenObject(memberScope, owner); |
| if (result is DummyMirror && owner.owner != null |
| && owner.owner is! DummyMirror) { |
| var aresult = Indexable.getDocgenObject(memberScope, owner.owner); |
| if (aresult is! DummyMirror) result = aresult; |
| } |
| if (result is DummyMirror) return packagePrefix + result.docName; |
| return result.packagePrefix + result.docName; |
| } |
| |
| if (owner != null) { |
| var result = owner.findElementInScope(name); |
| if (result != null) return result; |
| } |
| return super.findElementInScope(name); |
| } |
| |
| String get docName { |
| if ((mirror as MethodMirror).isConstructor) { |
| // We name constructors specially -- including the class name again and a |
| // "-" to separate the constructor from its name (if any). |
| return '${owner.docName}.${dart2js_util.nameOf(mirror.owner)}-' |
| '${dart2js_util.nameOf(mirror)}'; |
| } |
| return super.docName; |
| } |
| |
| String get fileName => packagePrefix + docName; |
| |
| /// Makes sure that the method with an inherited equivalent have comments. |
| void ensureCommentFor(Method inheritedMethod) { |
| if (comment.isNotEmpty) return; |
| |
| comment = inheritedMethod._commentToHtml(this); |
| _unresolvedComment = inheritedMethod._unresolvedComment; |
| commentInheritedFrom = inheritedMethod.commentInheritedFrom == '' ? |
| new DummyMirror(inheritedMethod.mirror).docName : |
| inheritedMethod.commentInheritedFrom; |
| } |
| |
| /// Generates a map describing the [Method] object. |
| Map toMap() => { |
| 'name': name, |
| 'qualifiedName': qualifiedName, |
| 'comment': comment, |
| 'commentFrom': (methodInheritedFrom != null && |
| commentInheritedFrom == methodInheritedFrom.docName ? '' |
| : commentInheritedFrom), |
| 'inheritedFrom': (methodInheritedFrom == null? '' : |
| originallyInheritedFrom.docName), |
| 'static': isStatic, |
| 'abstract': isAbstract, |
| 'constant': isConst, |
| 'return': new List.filled(1, returnType.toMap()), |
| 'parameters': recurseMap(parameters), |
| 'annotations': annotations.map((a) => a.toMap()).toList() |
| }; |
| |
| String get typeName { |
| MethodMirror theMirror = mirror; |
| if (theMirror.isConstructor) return 'constructor'; |
| if (theMirror.isGetter) return 'getter'; |
| if (theMirror.isSetter) return'setter'; |
| if (theMirror.isOperator) return 'operator'; |
| return 'method'; |
| } |
| |
| get comment { |
| if (_comment != null) return _comment; |
| if (owner is Class) { |
| (owner as Class).ensureComments(); |
| } |
| var result = super.comment; |
| if (result == '' && methodInheritedFrom != null) { |
| // This should be NOT from the MIRROR, but from the COMMENT. |
| methodInheritedFrom.comment; // Ensure comment field has been populated. |
| _unresolvedComment = methodInheritedFrom._unresolvedComment; |
| |
| var linkResolver = (name) => fixReference(name); |
| comment = _unresolvedComment == null ? '' : |
| markdown.markdownToHtml(_unresolvedComment.trim(), |
| linkResolver: linkResolver, inlineSyntaxes: _MARKDOWN_SYNTAXES); |
| commentInheritedFrom = comment != '' ? |
| methodInheritedFrom.commentInheritedFrom : ''; |
| result = comment; |
| } |
| return result; |
| } |
| |
| bool _isValidMirror(DeclarationMirror mirror) => mirror is MethodMirror; |
| } |
| |
| /// Docgen wrapper around the dart2js mirror for a Dart |
| /// method/function parameter. |
| class Parameter extends MirrorBased { |
| final ParameterMirror mirror; |
| final String name; |
| final bool isOptional; |
| final bool isNamed; |
| final bool hasDefaultValue; |
| final Type type; |
| final String defaultValue; |
| /// List of the meta annotations on the parameter. |
| final List<Annotation> annotations; |
| |
| Parameter(ParameterMirror mirror, Library owningLibrary) |
| : this.mirror = mirror, |
| name = dart2js_util.nameOf(mirror), |
| isOptional = mirror.isOptional, |
| isNamed = mirror.isNamed, |
| hasDefaultValue = mirror.hasDefaultValue, |
| defaultValue = '${mirror.defaultValue}', |
| type = new Type(mirror.type, owningLibrary), |
| annotations = _createAnnotations(mirror, owningLibrary); |
| |
| /// Generates a map describing the [Parameter] object. |
| Map toMap() => { |
| 'name': name, |
| 'optional': isOptional, |
| 'named': isNamed, |
| 'default': hasDefaultValue, |
| 'type': new List.filled(1, type.toMap()), |
| 'value': defaultValue, |
| 'annotations': annotations.map((a) => a.toMap()).toList() |
| }; |
| } |
| |
| /// Docgen wrapper around the mirror for a return type, and/or its generic |
| /// type parameters. |
| /// |
| /// Return types are of a form [outer]<[inner]>. |
| /// If there is no [inner] part, [inner] will be an empty list. |
| /// |
| /// For example: |
| /// int size() |
| /// "return" : |
| /// - "outer" : "dart-core.int" |
| /// "inner" : |
| /// |
| /// List<String> toList() |
| /// "return" : |
| /// - "outer" : "dart-core.List" |
| /// "inner" : |
| /// - "outer" : "dart-core.String" |
| /// "inner" : |
| /// |
| /// Map<String, List<int>> |
| /// "return" : |
| /// - "outer" : "dart-core.Map" |
| /// "inner" : |
| /// - "outer" : "dart-core.String" |
| /// "inner" : |
| /// - "outer" : "dart-core.List" |
| /// "inner" : |
| /// - "outer" : "dart-core.int" |
| /// "inner" : |
| class Type extends MirrorBased { |
| final TypeMirror mirror; |
| final Library owningLibrary; |
| |
| Type(this.mirror, this.owningLibrary); |
| |
| /// Returns a list of [Type] objects constructed from TypeMirrors. |
| List<Type> _createTypeGenerics(TypeMirror mirror) { |
| if (mirror is ClassMirror) { |
| var innerList = []; |
| mirror.typeArguments.forEach((e) { |
| innerList.add(new Type(e, owningLibrary)); |
| }); |
| return innerList; |
| } |
| return []; |
| } |
| |
| Map toMap() { |
| var result = Indexable.getDocgenObject(mirror, owningLibrary); |
| return { |
| // We may encounter types whose corresponding library has not been |
| // processed yet, so look up with the owningLibrary at the last moment. |
| 'outer': result.packagePrefix + result.docName, |
| 'inner': _createTypeGenerics(mirror).map((e) => e.toMap()).toList(), |
| }; |
| } |
| } |
| |
| /// Holds the name of the annotation, and its parameters. |
| class Annotation extends MirrorBased { |
| /// The class of this annotation. |
| final ClassMirror mirror; |
| final Library owningLibrary; |
| List<String> parameters; |
| |
| Annotation(InstanceMirror originalMirror, this.owningLibrary) |
| : mirror = originalMirror.type { |
| parameters = dart2js_util.variablesOf(originalMirror.type.declarations) |
| .where((e) => e.isFinal) |
| .map((e) => originalMirror.getField(e.simpleName).reflectee) |
| .where((e) => e != null) |
| .toList(); |
| } |
| |
| Map toMap() => { |
| 'name': Indexable.getDocgenObject(mirror, owningLibrary).docName, |
| 'parameters': parameters |
| }; |
| } |
| |
| /// Returns a list of meta annotations assocated with a mirror. |
| List<Annotation> _createAnnotations(DeclarationMirror mirror, |
| Library owningLibrary) { |
| var annotationMirrors = mirror.metadata.where((e) => |
| e is dart2js_mirrors.Dart2JsConstructedConstantMirror); |
| var annotations = []; |
| annotationMirrors.forEach((annotation) { |
| var docgenAnnotation = new Annotation(annotation, owningLibrary); |
| if (!_SKIPPED_ANNOTATIONS.contains( |
| dart2js_util.qualifiedNameOf(docgenAnnotation.mirror))) { |
| annotations.add(docgenAnnotation); |
| } |
| }); |
| return annotations; |
| } |