Privatize some of the interface of Canonicalization, Category (#2291)

Author: srawlins

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(', ')}";
 }

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;

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;