Index: pkg/docgen/lib/src/library_helpers.dart |
diff --git a/pkg/docgen/lib/src/library_helpers.dart b/pkg/docgen/lib/src/library_helpers.dart |
deleted file mode 100644 |
index 24e89d3f15cd22107ef8af1f821c0629dbc276b8..0000000000000000000000000000000000000000 |
--- a/pkg/docgen/lib/src/library_helpers.dart |
+++ /dev/null |
@@ -1,220 +0,0 @@ |
-// Copyright (c) 2014, the Dart project authors. Please see the AUTHORS file |
-// for details. All rights reserved. Use of this source code is governed by a |
-// BSD-style license that can be found in the LICENSE file. |
- |
-library docgen.library_helpers; |
- |
-import 'package:logging/logging.dart'; |
-import 'package:markdown/markdown.dart' as markdown; |
- |
-import 'exports/source_mirrors.dart'; |
-import 'exports/mirrors_util.dart' as dart2js_util; |
- |
-import 'models/indexable.dart'; |
-import 'models/library.dart'; |
-import 'models/dummy_mirror.dart'; |
- |
-typedef DeclarationMirror LookupFunction(DeclarationSourceMirror declaration, |
- String name); |
- |
-/// Support for [:foo:]-style code comments to the markdown parser. |
-final List<markdown.InlineSyntax> MARKDOWN_SYNTAXES = |
- [new markdown.CodeSyntax(r'\[:\s?((?:.|\n)*?)\s?:\]')]; |
- |
-bool get includePrivateMembers { |
- if (_includePrivate == null) { |
- throw new StateError('includePrivate has not been set'); |
- } |
- return _includePrivate; |
-} |
- |
-void set includePrivateMembers(bool value) { |
- if (value == null) throw new ArgumentError('includePrivate cannot be null'); |
- _includePrivate = value; |
-} |
- |
-bool _includePrivate; |
- |
-/// Return true if this item and all of its owners are all visible. |
-bool isFullChainVisible(Indexable item) { |
- return includePrivateMembers || (!item.isPrivate && (item.owner != null ? |
- isFullChainVisible(item.owner) : true)); |
-} |
- |
-/// Logger for printing out progress of documentation generation. |
-final Logger logger = new Logger('Docgen'); |
- |
-/// The dart:core library, which contains all types that are always available |
-/// without import. |
-Library coreLibrary; |
- |
-/// Set of libraries declared in the SDK, so libraries that can be accessed |
-/// when running dart by default. |
-Iterable<LibraryMirror> get sdkLibraries => _sdkLibraries; |
-Iterable<LibraryMirror> _sdkLibraries; |
- |
-////// Top level resolution functions |
-/// Converts all [foo] references in comments to <a>libraryName.foo</a>. |
-markdown.Node globalFixReference(String name) { |
- // Attempt the look up the whole name up in the scope. |
- String elementName = findElementInScopeWithPrefix(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. |
-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 = findElementInScopeWithPrefix(token, ''); |
- if (elementName != null) { |
- accumulatedHtml += markdown.renderToHtml([new markdown.Element.text('a', |
- elementName)]); |
- added = true; |
- } |
- } |
- if (!added) { |
- accumulatedHtml += token; |
- } |
- } |
- return new markdown.Text(accumulatedHtml); |
-} |
- |
-String findElementInScopeWithPrefix(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; |
-} |
- |
-/// 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. |
-Indexable getDocgenObject(DeclarationMirror mirror, [Indexable owner]) { |
- Map<String, Indexable> docgenObj = lookupIndexableMap(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.add(firstSet); |
- if (coreLibrary != null && docgenObj[coreLibrary.docName] != null) { |
- setToExamine.add(docgenObj[coreLibrary.docName]); |
- } |
- } else { |
- setToExamine.addAll(docgenObj.values); |
- } |
- |
- 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); |
-} |
- |
-void 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'))); |
-} |
- |
-/// For a given name, determine if we need to resolve it as a qualified name |
-/// or a simple name in the source mirors. |
-LookupFunction determineLookupFunc(String name) => name.contains('.') ? |
- dart2js_util.lookupQualifiedInScope : |
- (mirror, name) => mirror.lookupInScope(name); |
- |
-/// Chunk the provided name into individual parts to be resolved. We take a |
-/// simplistic approach to chunking, though, we break at " ", ",", "<" |
-/// and ">". All other characters are grouped into the name to be resolved. |
-/// As a result, these characters will all be treated as part of the item to |
-/// be resolved (aka the * is interpreted literally as a *, not as an |
-/// indicator for bold <em>. |
-List<String> _tokenizeComplexReference(String name) { |
- var tokens = []; |
- var append = false; |
- var index = 0; |
- while (index < name.length) { |
- if (name.indexOf(_LESS_THAN, index) == index) { |
- tokens.add(_LESS_THAN); |
- append = false; |
- index += _LESS_THAN.length; |
- } else if (name[index] == ' ' || name[index] == ',' || name[index] == '>') { |
- tokens.add(name[index]); |
- append = false; |
- index++; |
- } else { |
- if (append) { |
- tokens[tokens.length - 1] = tokens.last + name[index]; |
- } else { |
- tokens.add(name[index]); |
- append = true; |
- } |
- index++; |
- } |
- } |
- return tokens; |
-} |
- |
-// HTML escaped version of '<' character. |
-const _LESS_THAN = '<'; |