Add annotations to features (#1332)

This change addresses #1265 with a rearrangement of how the "features" section of italicized text is generated under each method or property.  Annotations, including custom annotations, are displayed, with the exception of "@OverRide" and "@deprecated" as those are indicated by other means in dartdoc.  Final is now indicated instead of read-only for variables/properties declared final.

Author: jcollins-g

CHANGELOG.md

@@ -1,3 +1,5 @@
+* add annotations to features line for methods, properties, constants (#1264)
+
 ## 0.9.10
 * de-emphasize and resort the inherited members (#641)
 * fix bug with showing parameterized typdefs in return types of properties (#1263)

lib/src/html/templates.dart

@@ -22,7 +22,7 @@ const _partials = const <String>[
   'head',
   'property',
   'styles_and_scripts',
-  'readable_writable',
+  'features',
   'documentation',
   'name_summary',
   'sidebar_for_class',

lib/src/model.dart

@@ -53,6 +53,31 @@ Map<String, Map<String, List<Map<String, dynamic>>>> get _crossdartJson {
 int byName(Nameable a, Nameable b) =>
     compareAsciiLowerCaseNatural(a.name, b.name);
 
+/// Items mapped less than zero will sort before custom annotations.
+/// Items mapped above zero are sorted after custom annotations.
+/// Items mapped to zero will sort alphabetically among custom annotations.
+/// Custom annotations are assumed to be any annotation or feature not in this
+/// map.
+const Map<String, int> featureOrder = const {
+  'read-only': 1,
+  'write-only': 1,
+  'read / write': 1,
+  'final': 2,
+  'inherited': 3,
+};
+
+int byFeatureOrdering(String a, String b) {
+  int scoreA = 0;
+  int scoreB = 0;
+
+  if (featureOrder.containsKey(a)) scoreA = featureOrder[a];
+  if (featureOrder.containsKey(b)) scoreB = featureOrder[b];
+
+  if (scoreA < scoreB) return -1;
+  if (scoreA > scoreB) return 1;
+  return compareAsciiLowerCaseNatural(a, b);
+}
+
 void _addToImplementors(Class c) {
   _implementors.putIfAbsent(c, () => []);
 
@@ -867,7 +892,12 @@ class Field extends ModelElement
   bool get isConst => _field.isConst;
 
   @override
-  bool get isFinal => _field.isFinal;
+  bool get isFinal {
+    /// isFinal returns true for the field even if it has an explicit getter
+    /// (which means we should not document it as "final").
+    if (hasExplicitGetter) return false;
+    return _field.isFinal;
+  }
 
   bool get isInherited => _isInherited;
 
@@ -883,6 +913,17 @@ class Field extends ModelElement
 
   bool get writeOnly => hasSetter && !hasGetter;
 
+  @override
+  Set<String> get features {
+    Set<String> all_features = super.features;
+    /// final/const implies read-only, so don't display both strings.
+    if (readOnly && !isFinal && !isConst) all_features.add('read-only');
+    if (writeOnly) all_features.add('write-only');
+    if (readWrite) all_features.add('read / write');
+    if (isInherited) all_features.add('inherited');
+    return all_features;
+  }
+
   @override
   String get _computeDocumentationComment {
     String docs = getterSetterDocumentationComment;
@@ -1326,6 +1367,13 @@ class Method extends ModelElement
 
   bool get isOperator => false;
 
+  @override
+  Set<String> get features {
+    Set<String> all_features = super.features;
+    if (isInherited) all_features.add('inherited');
+    return all_features;
+  }
+
   @override
   bool get isStatic => _method.isStatic;
 
@@ -1448,6 +1496,26 @@ abstract class ModelElement implements Comparable, Nameable, Documentable {
     }
   }
 
+  /// const and static are not needed here because const/static elements get
+  /// their own sections in the doc.
+  Set<String> get features {
+    Set<String> all_features = new Set<String>();
+    all_features.addAll(annotations);
+    /// override as an annotation should be replaced with direct information
+    /// from the analyzer if we decide to display it at this level.
+    all_features.remove('override');
+    /// Drop the plain "deprecated" annotation, that's indicated via
+    /// strikethroughs. Custom @Deprecated() will still appear.
+    all_features.remove('deprecated');
+    if (isFinal) all_features.add('final');
+    return all_features;
+  }
+
+  String get featuresAsString {
+    List<String> all_features = features.toList()..sort(byFeatureOrdering);
+    return all_features.join(', ');
+  }
+
   bool get canHaveParameters =>
       element is ExecutableElement || element is FunctionTypeAliasElement;
 
@@ -2477,7 +2545,12 @@ class TopLevelVariable extends ModelElement
   bool get isConst => _variable.isConst;
 
   @override
-  bool get isFinal => _variable.isFinal;
+  bool get isFinal {
+    /// isFinal returns true for the variable even if it has an explicit getter
+    /// (which means we should not document it as "final").
+    if (hasExplicitGetter) return false;
+    return _variable.isFinal;
+  }
 
   @override
   String get kind => 'top-level property';
@@ -2488,6 +2561,17 @@ class TopLevelVariable extends ModelElement
   bool get readWrite => hasGetter && hasSetter;
 
   bool get writeOnly => hasSetter && !hasGetter;
+
+  @override
+  Set<String> get features {
+    Set<String> all_features = super.features;
+    /// final/const implies read-only, so don't display both strings.
+    if (readOnly && !isFinal && !isConst) all_features.add('read-only');
+    if (writeOnly) all_features.add('write-only');
+    if (readWrite) all_features.add('read / write');
+    return all_features;
+  }
+
   @override
   String get _computeDocumentationComment {
     String docs = getterSetterDocumentationComment;

lib/templates/_callable.html

@@ -5,7 +5,5 @@
 </dt>
 <dd{{ #isInherited }} class="inherited"{{ /isInherited}}>
   {{{ oneLineDoc }}}
-  {{#isInherited}}
-  <div class="features">inherited</div>
-  {{/isInherited}}
+  {{>features}}
 </dd>

lib/templates/_constant.html

@@ -4,6 +4,7 @@
 </dt>
 <dd>
   {{{ oneLineDoc }}}
+  {{>features}}
   <div>
     <span class="signature"><code>{{{ constantValueTruncated }}}</code></span>
   </div>

lib/templates/_features.html

@@ -0,0 +1 @@
+{{ #featuresAsString.isNotEmpty }}<div class="features">{{{featuresAsString}}}</div>{{ /featuresAsString.isNotEmpty }}

lib/templates/_property.html

@@ -4,5 +4,5 @@
 </dt>
 <dd{{ #isInherited }} class="inherited"{{ /isInherited}}>
   {{{ oneLineDoc }}}
-  {{>readable_writable}}
+  {{>features}}
 </dd>

lib/templates/_readable_writable.html

@@ -15,7 +15,7 @@ <h5><a href="{{href}}">{{name}}</a></h5>
     <section class="multi-line-signature">
       <span class="returntype">{{{ linkedReturnType }}}</span>
         {{>name_summary}}
-        {{>readable_writable}}
+        {{>features}}
     </section>
 
     {{>documentation}}

lib/templates/property.html

@@ -14,6 +14,7 @@ <h5><a href="{{href}}">{{name}}</a></h5>
         {{>name_summary}}
         =
         <span class="constant-value">{{{ constantValue }}}</span>
+        {{>features}}
       {{/property}}
     </section>