More documentation clean-up for server APIs

pkg/analysis_server/lib/analysis/index_core.dart

 // Copyright (c) 2015, 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.
 
 library analysis_server.analysis.index.index_core;
 
 import 'dart:async';
 import 'dart:collection';
 
 import 'package:analysis_server/src/services/index/index.dart';
 import 'package:analyzer/src/generated/engine.dart';
 import 'package:analyzer/src/generated/source.dart';
 
 /**
- * Return the integer value that corresponds to the given [str].
- * The value of [str] may be `null`.
+ * Return the integer value that corresponds to the given [string]. The value of
+ * [string] may be `null`.
+ *
+ * Clients are not expected to implement this signature. A function of this type
+ * is provided by the framework to clients in order to implement the method
+ * [IndexableObjectKind.encodeHash].
  */
-typedef int StringToInt(String str);
+typedef int StringToInt(String string);
 
 /**
  * An object that can have a [Relationship] with various [Location]s in a code
  * base. The object is abstractly represented by a [kind] and an [offset] within
  * a [source].
  *
  * Clients must ensure that two distinct objects in the same source cannot have
  * the same kind and offset. Failure to do so will make it impossible for
  * clients to identify the model element corresponding to the indexable object.
  *
@@ skipping 88 matching lines @@
    */
   static void register(IndexableObjectKind kind) {
     int index = kind.index;
     if (_registry.containsKey(index)) {
       throw new ArgumentError('duplicate index for kind: $index');
     }
     _registry[index] = kind;
   }
 }
 
-// A sketch of what the driver routine might look like:
-//
-//void buildIndexForSource(AnalysisContext context, Source source) {
-//  IndexStoreImpl store;
-//  store.aboutToIndex(context, source);
-//  try {
-//    for (IndexContributor contributor in contributors) {
-//      contributor.contributeTo(store, context, source);
-//    }
-//  } finally {
-//    store.doneIndexing();
-//  }
-//}
-
 /**
  * An object used to add relationships to the index.
  *
  * Clients are expected to subtype this class when implementing plugins.
  */
 abstract class IndexContributor {
   /**
    * Contribute relationships existing in the given [object] to the given
    * index [store] in the given [context].
    */
@@ skipping 130 matching lines @@
  */
 abstract class Relationship {
   /**
    * Return a relationship that has the given [identifier]. If the relationship
    * has already been created, then it will be returned, otherwise a new
    * relationship will be created
    */
   factory Relationship(String identifier) =>
       RelationshipImpl.getRelationship(identifier);
 }