documentation updates from review comments

Author: Stephan Brandauer

java/ql/src/Telemetry/AutomodelFrameworkModeCharacteristics.qll

@@ -31,6 +31,7 @@ abstract class MetadataExtractor extends string {
   );
 }
 
+// for documentation of the implementations here, see the QLDoc in the CandidateSig signature module.
 module FrameworkCandidatesImpl implements SharedCharacteristics::CandidateSig {
   class Endpoint = DataFlow::ParameterNode;
 
@@ -101,6 +102,11 @@ module FrameworkCandidatesImpl implements SharedCharacteristics::CandidateSig {
     exists(int paramIdx | e.isParameterOf(_, paramIdx) | input = "Argument[" + paramIdx + "]")
   }
 
+  /**
+   * Returns the related location for the given endpoint.
+   *
+   * Related locations can be JavaDoc comments of the class or the method.
+   */
   RelatedLocation getRelatedLocation(Endpoint e, string name) {
     name = "Callable-JavaDoc" and
     result = FrameworkCandidatesImpl::getCallable(e).(Documentable).getJavadoc()

java/ql/src/Telemetry/AutomodelSharedCharacteristics.qll

@@ -55,6 +55,12 @@ signature module CandidateSig {
    */
   predicate isNeutral(Endpoint e);
 
+  /**
+   * A related location is a source code location that may hold extra information about an endpoint that can be useful
+   * to the machine learning model.
+   *
+   * For example, a related location for a method call may be the documentation comment of a method.
+   */
   RelatedLocation getRelatedLocation(Endpoint e, string name);
 }
 
@@ -95,8 +101,8 @@ module SharedCharacteristics<CandidateSig Candidate> {
   }
 
   /**
-   * If it exists, gets a related location for a given endpoint or candidate.
-   * If it doesn't exist, returns the candidate itself as a 'null' value.
+   * Gets the related location of `e` with name `name`, if it exists.
+   * Otherwise, gets the candidate itself.
    */
   bindingset[name]
   Candidate::RelatedLocation getRelatedLocationOrCandidate(Candidate::Endpoint e, string name) {
@@ -115,8 +121,8 @@ module SharedCharacteristics<CandidateSig Candidate> {
     // An endpoint is a sink candidate if none of its characteristics give much indication whether or not it is a sink.
     not sinkType instanceof Candidate::NegativeEndpointType and
     result.appliesToEndpoint(candidateSink) and
-    // Exclude endpoints that have a characteristic that implies they're not sinks for _any_ sink type.
     (
+      // Exclude endpoints that have a characteristic that implies they're not sinks for _any_ sink type.
       exists(float confidence |
         confidence >= mediumConfidence() and
         result.hasImplications(any(Candidate::NegativeEndpointType t), true, confidence)
@@ -144,8 +150,7 @@ module SharedCharacteristics<CandidateSig Candidate> {
     EndpointCharacteristic() { any() }
 
     /**
-     * Holds for parameters that have this characteristic. This predicate contains the logic that applies characteristics
-     * to the appropriate set of dataflow parameters.
+     * Holds for endpoints that have this characteristic.
      */
     abstract predicate appliesToEndpoint(Candidate::Endpoint n);