updates to the analysis server generated spec doc

pkg/analysis_server/lib/plugin/protocol/generated_protocol.dart

 // Copyright (c) 2014, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 //
 // This file has been automatically generated.  Please do not edit it manually.
 // To regenerate the file, use the script
 // "pkg/analysis_server/tool/spec/generate_files".
 
 part of analysis_server.plugin.protocol.protocol;
 
@@ skipping 9156 matching lines @@
 
   bool _enableSuperMixins;
 
   bool _generateDart2jsHints;
 
   bool _generateHints;
 
   bool _generateLints;
 
   /**
-   * Deprecated: this feature is always enabled.
+   * @deprecated: this feature is always enabled.

[Brian Wilkerson, 2017/04/09 16:30:53]

Personally, I like the old style better. I don't think the at sign adds any
value either here or in the specification, despite the similarity to the
annotation. This isn't Dart; it just adds one more special character to have to
parse while reading it. You replaced a pair or parentheses with a colon, which I
assume is to make the text visually less bulky, so I don't understand adding an
extra character here when it has the opposite effect.

That said, it would be interesting to consider adding the actual annotation to
the generated code:

/**
 * Deprecated: this feature is always enabled.
 *
 * True if the client wants to enable support for the proposed async feature.
 */
@deprecated
bool get enableAsync => _enableAsync;

This might result in a lot of extraneous hints in the analysis_server package,
though, because we still have to reference these members until we actually
remove them from the API.

[devoncarew, 2017/04/09 19:43:21]

Sure, I moved back to the 'Deprecated:' text. Will experiment with actual
@deprected annotations in the generated libraries.
That change was because the properties looked a bit like method declarations to
me; I think the 'foo: String' rendering is a little less confusing.

    *
    * True if the client wants to enable support for the proposed async feature.
    */
   bool get enableAsync => _enableAsync;
 
   /**
-   * Deprecated: this feature is always enabled.
+   * @deprecated: this feature is always enabled.
    *
    * True if the client wants to enable support for the proposed async feature.
    */
   void set enableAsync(bool value) {
     this._enableAsync = value;
   }
 
   /**
-   * Deprecated: this feature is always enabled.
+   * @deprecated: this feature is always enabled.
    *
    * True if the client wants to enable support for the proposed deferred
    * loading feature.
    */
   bool get enableDeferredLoading => _enableDeferredLoading;
 
   /**
-   * Deprecated: this feature is always enabled.
+   * @deprecated: this feature is always enabled.
    *
    * True if the client wants to enable support for the proposed deferred
    * loading feature.
    */
   void set enableDeferredLoading(bool value) {
     this._enableDeferredLoading = value;
   }
 
   /**
-   * Deprecated: this feature is always enabled.
+   * @deprecated: this feature is always enabled.
    *
    * True if the client wants to enable support for the proposed enum feature.
    */
   bool get enableEnums => _enableEnums;
 
   /**
-   * Deprecated: this feature is always enabled.
+   * @deprecated: this feature is always enabled.
    *
    * True if the client wants to enable support for the proposed enum feature.
    */
   void set enableEnums(bool value) {
     this._enableEnums = value;
   }
 
   /**
-   * Deprecated: this feature is always enabled.
+   * @deprecated: this feature is always enabled.
    *
    * True if the client wants to enable support for the proposed "null aware
    * operators" feature.
    */
   bool get enableNullAwareOperators => _enableNullAwareOperators;
 
   /**
-   * Deprecated: this feature is always enabled.
+   * @deprecated: this feature is always enabled.
    *
    * True if the client wants to enable support for the proposed "null aware
    * operators" feature.
    */
   void set enableNullAwareOperators(bool value) {
     this._enableNullAwareOperators = value;
   }
 
   /**
    * True if the client wants to enable support for the proposed "less
@@ skipping 1855 matching lines @@
 
   static const ElementKind SETTER = const ElementKind._("SETTER");
 
   static const ElementKind TOP_LEVEL_VARIABLE =
       const ElementKind._("TOP_LEVEL_VARIABLE");
 
   static const ElementKind TYPE_PARAMETER =
       const ElementKind._("TYPE_PARAMETER");
 
   /**
-   * Deprecated: support for tests was removed.
+   * @deprecated: support for tests was removed.
    */
   static const ElementKind UNIT_TEST_GROUP =
       const ElementKind._("UNIT_TEST_GROUP");
 
   /**
-   * Deprecated: support for tests was removed.
+   * @deprecated: support for tests was removed.
    */
   static const ElementKind UNIT_TEST_TEST =
       const ElementKind._("UNIT_TEST_TEST");
 
   static const ElementKind UNKNOWN = const ElementKind._("UNKNOWN");
 
   /**
    * A list containing all of the enum values that are defined.
    */
   static const List<ElementKind> VALUES = const <ElementKind>[
@@ skipping 7526 matching lines @@
     return false;
   }
 
   @override
   int get hashCode {
     int hash = 0;
     hash = JenkinsSmiHash.combine(hash, newName.hashCode);
     return JenkinsSmiHash.finish(hash);
   }
 }