Skip to content
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

Privatize some of the interface of Canonicalization, Category #2291

Merged
merged 1 commit into from
Aug 11, 2020
Merged

Privatize some of the interface of Canonicalization, Category #2291

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
56 changes: 42 additions & 14 deletions lib/src/model/canonicalization.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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) {
Expand All @@ -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');
Expand All @@ -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);
Expand All @@ -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(', ')}";
}
34 changes: 29 additions & 5 deletions lib/src/model/category.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 = [];
Expand All @@ -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;
Expand Down Expand Up @@ -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;
Expand Down
2 changes: 1 addition & 1 deletion lib/src/model/top_level_variable.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down