From b6b0f5f46ff2703a2b475cb25a005b67bb1e53a9 Mon Sep 17 00:00:00 2001
From: Sam Rawlins <srawlins@google.com>
Date: Mon, 10 Aug 2020 22:25:58 -0700
Subject: [PATCH] Privatize some of the interface of Canonicalization, Category
---
lib/src/model/canonicalization.dart | 56 ++++++++++++++++++++-------
lib/src/model/category.dart | 34 +++++++++++++---
lib/src/model/top_level_variable.dart | 2 +-
3 files changed, 72 insertions(+), 20 deletions(-)
diff --git a/lib/src/model/canonicalization.dart b/lib/src/model/canonicalization.dart
index be33a0468f..c7b31b08db 100644
--- a/lib/src/model/canonicalization.dart
+++ b/lib/src/model/canonicalization.dart
@@ -16,10 +16,10 @@ abstract class Canonicalization implements Locatable, Documentable {
Set<String> get locationPieces;
List<ScoredCandidate> scoreCanonicalCandidates(Iterable<Library> libraries) {
- return libraries.map(scoreElementWithLibrary).toList()..sort();
+ return libraries.map(_scoreElementWithLibrary).toList()..sort();
}
- ScoredCandidate scoreElementWithLibrary(Library lib) {
+ ScoredCandidate _scoreElementWithLibrary(Library lib) {
var scoredCandidate = ScoredCandidate(this, lib);
Iterable<String> resplit(Set<String> items) sync* {
for (var item in items) {
@@ -31,23 +31,23 @@ abstract class Canonicalization implements Locatable, Documentable {
// Large boost for @canonicalFor, essentially overriding all other concerns.
if (lib.canonicalFor.contains(fullyQualifiedName)) {
- scoredCandidate.alterScore(5.0, 'marked @canonicalFor');
+ scoredCandidate._alterScore(5.0, 'marked @canonicalFor');
}
// Penalty for deprecated libraries.
- if (lib.isDeprecated) scoredCandidate.alterScore(-1.0, 'is deprecated');
+ if (lib.isDeprecated) scoredCandidate._alterScore(-1.0, 'is deprecated');
// Give a big boost if the library has the package name embedded in it.
if (lib.package.namePieces.intersection(lib.namePieces).isEmpty) {
- scoredCandidate.alterScore(1.0, 'embeds package name');
+ scoredCandidate._alterScore(1.0, 'embeds package name');
}
// Give a tiny boost for libraries with long names, assuming they're
// more specific (and therefore more likely to be the owner of this symbol).
- scoredCandidate.alterScore(.01 * lib.namePieces.length, 'name is long');
+ scoredCandidate._alterScore(.01 * lib.namePieces.length, 'name is long');
// If we don't know the location of this element, return our best guess.
// TODO(jcollins-g): is that even possible?
assert(locationPieces.isNotEmpty);
if (locationPieces.isEmpty) return scoredCandidate;
// The more pieces we have of the location in our library name, the more we should boost our score.
- scoredCandidate.alterScore(
+ scoredCandidate._alterScore(
lib.namePieces.intersection(locationPieces).length.toDouble() /
locationPieces.length.toDouble(),
'element location shares parts with name');
@@ -60,35 +60,63 @@ abstract class Canonicalization implements Locatable, Documentable {
}
}
}
- scoredCandidate.alterScore(
+ scoredCandidate._alterScore(
scoreBoost, 'element location parts start with parts of name');
return scoredCandidate;
}
+
+ @Deprecated(
+ 'Public method intended to be private; will be removed as early as '
+ 'Dartdoc 1.0.0')
+ ScoredCandidate scoreElementWithLibrary(Library lib) =>
+ _scoreElementWithLibrary(lib);
}
/// This class represents the score for a particular element; how likely
/// it is that this is the canonical element.
class ScoredCandidate implements Comparable<ScoredCandidate> {
- final List<String> reasons = [];
+ final List<String> _reasons = [];
+
+ @Deprecated(
+ 'Public field intended to be private; will be removed as early as '
+ 'Dartdoc 1.0.0')
+ List<String> get reasons => _reasons;
+
+ @Deprecated(
+ 'Public field intended to be private; will be removed as early as '
+ 'Dartdoc 1.0.0')
+ set reasons(List<String> value) => reasons = value;
/// The canonicalization element being scored.
- final Canonicalization element;
+ final Canonicalization _element;
+
+ @Deprecated(
+ 'Public getter intended to be private; will be removed as early as '
+ 'Dartdoc 1.0.0')
+ Canonicalization get element => _element;
+
final Library library;
/// The score accumulated so far. Higher means it is more likely that this
/// is the intended canonical Library.
double score = 0.0;
- ScoredCandidate(this.element, this.library);
+ ScoredCandidate(this._element, this.library);
- void alterScore(double scoreDelta, String reason) {
+ void _alterScore(double scoreDelta, String reason) {
score += scoreDelta;
if (scoreDelta != 0) {
- reasons.add(
+ _reasons.add(
"${reason} (${scoreDelta >= 0 ? '+' : ''}${scoreDelta.toStringAsPrecision(4)})");
}
}
+ @Deprecated(
+ 'Public method intended to be private; will be removed as early as '
+ 'Dartdoc 1.0.0')
+ void alterScore(double scoreDelta, String reason) =>
+ _alterScore(scoreDelta, reason);
+
@override
int compareTo(ScoredCandidate other) {
//assert(element == other.element);
@@ -97,5 +125,5 @@ class ScoredCandidate implements Comparable<ScoredCandidate> {
@override
String toString() =>
- "${library.name}: ${score.toStringAsPrecision(4)} - ${reasons.join(', ')}";
+ "${library.name}: ${score.toStringAsPrecision(4)} - ${_reasons.join(', ')}";
}
diff --git a/lib/src/model/category.dart b/lib/src/model/category.dart
index f9a9a38fe6..6227ef9e69 100644
--- a/lib/src/model/category.dart
+++ b/lib/src/model/category.dart
@@ -24,11 +24,26 @@ class Category extends Nameable
Indexable
implements Documentable {
/// All libraries in [libraries] must come from [package].
+ Package _package;
+
@override
- Package package;
+ Package get package => _package;
+
+ @Deprecated('Field intended to be final; setter will be removed as early as '
+ 'Dartdoc 1.0.0')
+ set package(Package value) => _package = value;
+
final String _name;
+
+ DartdocOptionContext _config;
+
@override
- DartdocOptionContext config;
+ DartdocOptionContext get config => _config;
+
+ @Deprecated('Field intended to be final; setter will be removed as early as '
+ 'Dartdoc 1.0.0')
+ set config(DartdocOptionContext value) => _config = value;
+
final Set<Categorization> _allItems = {};
final List<Class> _classes = [];
@@ -41,7 +56,7 @@ class Category extends Nameable
final List<ModelFunction> _functions = [];
final List<Typedef> _typedefs = [];
- Category(this._name, this.package, this.config);
+ Category(this._name, this._package, this._config);
void addItem(Categorization c) {
if (_allItems.contains(c)) return;
@@ -118,15 +133,24 @@ class Category extends Nameable
@override
String get fullyQualifiedName => name;
- String get fileType => package.fileType;
+ String get _fileType => package.fileType;
+
+ @Deprecated(
+ 'Public field intended to be private; will be removed as early as '
+ 'Dartdoc 1.0.0')
+ String get fileType => _fileType;
- String get filePath => 'topics/$name-topic.$fileType';
+ String get filePath => 'topics/$name-topic.$_fileType';
@override
String get href => isCanonical ? '${package.baseHref}$filePath' : null;
+ @Deprecated(
+ 'Public field is unused; will be removed as early as Dartdoc 1.0.0')
String get categoryLabel => _categoryRenderer.renderCategoryLabel(this);
+ @Deprecated(
+ 'Public field is unused; will be removed as early as Dartdoc 1.0.0')
String get linkedName => _categoryRenderer.renderLinkedName(this);
int _categoryIndex;
diff --git a/lib/src/model/top_level_variable.dart b/lib/src/model/top_level_variable.dart
index e48d109c36..8bc611f4b8 100644
--- a/lib/src/model/top_level_variable.dart
+++ b/lib/src/model/top_level_variable.dart
@@ -8,7 +8,7 @@ import 'package:dartdoc/src/model/model.dart';
/// Top-level variables. But also picks up getters and setters?
class TopLevelVariable extends ModelElement
- with Canonicalization, GetterSetterCombo, Categorization
+ with GetterSetterCombo, Categorization
implements EnclosedElement {
@override
final Accessor getter;