Skip to content

refactor: begin extracting per-package data out from Package #1622

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 2, 2018
Merged

refactor: begin extracting per-package data out from Package #1622

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4d4315a
Begin extracting per-package data out from Package
jcollins-g Feb 28, 2018
9fa875c
Template update
jcollins-g Feb 28, 2018
2f37611
pubspec.lock change
jcollins-g Mar 2, 2018
0467e89
remove a bunch of autogenerated snapshot files?
jcollins-g Mar 2, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
67 changes: 35 additions & 32 deletions lib/dartdoc.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,7 +147,7 @@ class DartDoc extends PackageBuilder {
}
}

Package package;
PackageGraph packageGraph;

/// Generate DartDoc documentation.
///
Expand All @@ -157,23 +157,23 @@ class DartDoc extends PackageBuilder {
Future<DartDocResults> generateDocs() async {
Stopwatch _stopwatch = new Stopwatch()..start();
double seconds;
package = await buildPackage();
packageGraph = await buildPackageGraph();
seconds = _stopwatch.elapsedMilliseconds / 1000.0;
logInfo(
"Initialized dartdoc with ${package.libraries.length} librar${package.libraries.length == 1 ? 'y' : 'ies'} "
"Initialized dartdoc with ${packageGraph.libraries.length} librar${packageGraph.libraries.length == 1 ? 'y' : 'ies'} "
"in ${seconds.toStringAsFixed(1)} seconds");
_stopwatch.reset();

// Create the out directory.
if (!outputDir.existsSync()) outputDir.createSync(recursive: true);

for (var generator in generators) {
await generator.generate(package, outputDir.path);
await generator.generate(packageGraph, outputDir.path);
writtenFiles.addAll(generator.writtenFiles.map(path.normalize));
}
if (config.validateLinks) validateLinks(package, outputDir.path);
int warnings = package.packageWarningCounter.warningCount;
int errors = package.packageWarningCounter.errorCount;
if (config.validateLinks) validateLinks(packageGraph, outputDir.path);
int warnings = packageGraph.packageWarningCounter.warningCount;
int errors = packageGraph.packageWarningCounter.errorCount;
if (warnings == 0 && errors == 0) {
logInfo("no issues found");
} else {
Expand All @@ -183,23 +183,24 @@ class DartDoc extends PackageBuilder {

seconds = _stopwatch.elapsedMilliseconds / 1000.0;
logInfo(
"Documented ${package.publicLibraries.length} public librar${package.publicLibraries.length == 1 ? 'y' : 'ies'} "
"Documented ${packageGraph.publicLibraries.length} public librar${packageGraph.publicLibraries.length == 1 ? 'y' : 'ies'} "
"in ${seconds.toStringAsFixed(1)} seconds");

if (package.publicLibraries.isEmpty) {
if (packageGraph.publicLibraries.isEmpty) {
throw new DartDocFailure(
"dartdoc could not find any libraries to document. Run `pub get` and try again.");
}

if (package.packageWarningCounter.errorCount > 0) {
if (packageGraph.packageWarningCounter.errorCount > 0) {
throw new DartDocFailure("dartdoc encountered errors while processing");
}

return new DartDocResults(packageMeta, package, outputDir);
return new DartDocResults(packageMeta, packageGraph, outputDir);
}

/// Warn on file paths.
void _warn(Package package, PackageWarning kind, String warnOn, String origin,
void _warn(PackageGraph packageGraph, PackageWarning kind, String warnOn,
String origin,
{String referredFrom}) {
// Ordinarily this would go in [Package.warn], but we don't actually know what
// ModelElement to warn on yet.
Expand Down Expand Up @@ -235,14 +236,15 @@ class DartDoc extends PackageBuilder {
}

if (referredFromElements.isEmpty && referredFrom == 'index.html')
referredFromElements.add(package);
referredFromElements.add(packageGraph);
String message = warnOn;
if (referredFrom == 'index.json') message = '$warnOn (from index.json)';
package.warnOnElement(warnOnElement, kind,
packageGraph.warnOnElement(warnOnElement, kind,
message: message, referredFrom: referredFromElements);
}

void _doOrphanCheck(Package package, String origin, Set<String> visited) {
void _doOrphanCheck(
PackageGraph packageGraph, String origin, Set<String> visited) {
String normalOrigin = path.normalize(origin);
String staticAssets = path.joinAll([normalOrigin, 'static-assets', '']);
String indexJson = path.joinAll([normalOrigin, 'index.json']);
Expand All @@ -264,15 +266,16 @@ class DartDoc extends PackageBuilder {
if (visited.contains(fullPath)) continue;
if (!writtenFiles.contains(fullPath)) {
// This isn't a file we wrote (this time); don't claim we did.
_warn(package, PackageWarning.unknownFile, fullPath, normalOrigin);
_warn(packageGraph, PackageWarning.unknownFile, fullPath, normalOrigin);
} else {
_warn(package, PackageWarning.orphanedFile, fullPath, normalOrigin);
_warn(
packageGraph, PackageWarning.orphanedFile, fullPath, normalOrigin);
}
_onCheckProgress.add(fullPath);
}

if (!foundIndexJson) {
_warn(package, PackageWarning.brokenLink, indexJson, normalOrigin);
_warn(packageGraph, PackageWarning.brokenLink, indexJson, normalOrigin);
_onCheckProgress.add(indexJson);
}
}
Expand Down Expand Up @@ -300,7 +303,7 @@ class DartDoc extends PackageBuilder {
}

void _doSearchIndexCheck(
Package package, String origin, Set<String> visited) {
PackageGraph packageGraph, String origin, Set<String> visited) {
String fullPath = path.joinAll([origin, 'index.json']);
String indexPath = path.joinAll([origin, 'index.html']);
File file = new File("$fullPath");
Expand All @@ -319,7 +322,7 @@ class DartDoc extends PackageBuilder {
if (entry.containsKey('href')) {
String entryPath = path.joinAll([origin, entry['href']]);
if (!visited.contains(entryPath)) {
_warn(package, PackageWarning.brokenLink, entryPath,
_warn(packageGraph, PackageWarning.brokenLink, entryPath,
path.normalize(origin),
referredFrom: fullPath);
}
Expand All @@ -329,14 +332,14 @@ class DartDoc extends PackageBuilder {
// Missing from search index
Set<String> missing_from_search = visited.difference(found);
for (String s in missing_from_search) {
_warn(package, PackageWarning.missingFromSearchIndex, s,
_warn(packageGraph, PackageWarning.missingFromSearchIndex, s,
path.normalize(origin),
referredFrom: fullPath);
}
}

void _doCheck(
Package package, String origin, Set<String> visited, String pathToCheck,
void _doCheck(PackageGraph packageGraph, String origin, Set<String> visited,
String pathToCheck,
[String source, String fullPath]) {
if (fullPath == null) {
fullPath = path.joinAll([origin, pathToCheck]);
Expand All @@ -345,7 +348,7 @@ class DartDoc extends PackageBuilder {

Tuple2 stringLinksAndHref = _getStringLinksAndHref(fullPath);
if (stringLinksAndHref == null) {
_warn(package, PackageWarning.brokenLink, pathToCheck,
_warn(packageGraph, PackageWarning.brokenLink, pathToCheck,
path.normalize(origin),
referredFrom: source);
_onCheckProgress.add(pathToCheck);
Expand Down Expand Up @@ -387,7 +390,7 @@ class DartDoc extends PackageBuilder {
}
}
for (Tuple2 visitPaths in toVisit) {
_doCheck(package, origin, visited, visitPaths.item1, pathToCheck,
_doCheck(packageGraph, origin, visited, visitPaths.item1, pathToCheck,
visitPaths.item2);
}
_onCheckProgress.add(pathToCheck);
Expand All @@ -397,16 +400,16 @@ class DartDoc extends PackageBuilder {

/// Don't call this method more than once, and only after you've
/// generated all docs for the Package.
void validateLinks(Package package, String origin) {
void validateLinks(PackageGraph packageGraph, String origin) {
assert(_hrefs == null);
_hrefs = package.allHrefs;
_hrefs = packageGraph.allHrefs;

final Set<String> visited = new Set();
final String start = 'index.html';
logInfo('Validating docs...');
_doCheck(package, origin, visited, start);
_doOrphanCheck(package, origin, visited);
_doSearchIndexCheck(package, origin, visited);
_doCheck(packageGraph, origin, visited, start);
_doOrphanCheck(packageGraph, origin, visited);
_doSearchIndexCheck(packageGraph, origin, visited);
}
}

Expand All @@ -424,10 +427,10 @@ class DartDocFailure {
/// The results of a [DartDoc.generateDocs] call.
class DartDocResults {
final PackageMeta packageMeta;
final Package package;
final PackageGraph packageGraph;
final Directory outDir;

DartDocResults(this.packageMeta, this.package, this.outDir);
DartDocResults(this.packageMeta, this.packageGraph, this.outDir);
}

class _Error implements Comparable<_Error> {
Expand Down
4 changes: 2 additions & 2 deletions lib/src/element_type.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ class ElementType extends Privacy {
@override
bool get isPublic {
Class canonicalClass =
element.package.findCanonicalModelElementFor(element.element) ??
element.packageGraph.findCanonicalModelElementFor(element.element) ??
element;
return canonicalClass.isPublic;
}
Expand Down Expand Up @@ -139,7 +139,7 @@ class ElementType extends Privacy {

ElementType get _returnType {
var rt = _returnTypeCore;
Library lib = element.package.findLibraryFor(rt.element);
Library lib = element.packageGraph.findLibraryFor(rt.element);
if (lib == null) {
lib = new ModelElement.from(rt.element.library, element.library);
}
Expand Down
4 changes: 2 additions & 2 deletions lib/src/generator.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ library dartdoc.generator;
import 'dart:async' show Stream, Future;
import 'dart:io' show File;

import 'model.dart' show Package;
import 'model.dart' show PackageGraph;

/// An abstract class that defines a generator that generates documentation for
/// a given package.
Expand All @@ -17,7 +17,7 @@ import 'model.dart' show Package;
abstract class Generator {
/// Generate the documentation for the given package in the specified
/// directory. Completes the returned future when done.
Future generate(Package package, String outputDirectoryPath);
Future generate(PackageGraph packageGraph, String outputDirectoryPath);

/// Fires when a file is created.
Stream<File> get onFileCreated;
Expand Down
6 changes: 3 additions & 3 deletions lib/src/html/html_generator.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,9 +67,9 @@ class HtmlGenerator extends Generator {

@override

/// Actually write out the documentation for [package].
/// Actually write out the documentation for [packageGraph].
/// Stores the HtmlGeneratorInstance so we can access it in [writtenFiles].
Future generate(Package package, String outputDirectoryPath) async {
Future generate(PackageGraph packageGraph, String outputDirectoryPath) async {
assert(_instance == null);

var enabled = true;
Expand Down Expand Up @@ -102,7 +102,7 @@ class HtmlGenerator extends Generator {

try {
_instance =
new HtmlGeneratorInstance(_options, _templates, package, write);
new HtmlGeneratorInstance(_options, _templates, packageGraph, write);
await _instance.generate();
} finally {
enabled = false;
Expand Down
Loading