Merge pull request #7679 from erik-krogh/ql-doc-style

Approved by esbena

Author: codeql-ci

javascript/ql/lib/semmle/javascript/Externs.qll

@@ -544,7 +544,7 @@ class ExternalInterface extends ExternalType {
 }
 
 /**
- * Externs definition for the Function object.
+ * The externs definition for the Function object.
  *
  * Example:
  *
@@ -561,7 +561,7 @@ class FunctionExternal extends ExternalConstructor {
 }
 
 /**
- * Externs definition for the Object object.
+ * The externs definition for the Object object.
  *
  * Example:
  *
@@ -578,7 +578,7 @@ class ObjectExternal extends ExternalConstructor {
 }
 
 /**
- * Externs definition for the Array object.
+ * The externs definition for the Array object.
  *
  * Example:
  *

javascript/ql/lib/semmle/javascript/Promises.qll

@@ -707,7 +707,7 @@ private module DynamicImportSteps {
  */
 module Promisify {
   /**
-   * Gets a call to a `promisifyAll` function.
+   * A call to a `promisifyAll` function.
    * E.g. `require("bluebird").promisifyAll(...)`.
    */
   class PromisifyAllCall extends DataFlow::CallNode {
@@ -721,7 +721,7 @@ module Promisify {
   }
 
   /**
-   * Gets a call to a `promisify` function.
+   * A call to a `promisify` function.
    * E.g. `require("util").promisify(...)`.
    */
   class PromisifyCall extends DataFlow::CallNode {

javascript/ql/lib/semmle/javascript/StringOps.qll

@@ -512,7 +512,7 @@ module StringOps {
   }
 
   /**
-   * One of the operands in a string concatenation.
+   * An operand in a string concatenation.
    *
    * Examples:
    * ```

javascript/ql/lib/semmle/javascript/TypeScript.qll

@@ -1644,7 +1644,7 @@ class EnumMember extends ASTNode, @enum_member {
 }
 
 /**
- * Scope induced by an interface declaration, containing the type parameters declared on the interface.
+ * A scope induced by an interface declaration, containing the type parameters declared on the interface.
  *
  * Interfaces that do not declare type parameters have no scope object.
  */
@@ -1653,7 +1653,7 @@ class InterfaceScope extends @interface_scope, Scope {
 }
 
 /**
- * Scope induced by a type alias declaration, containing the type parameters declared the the alias.
+ * A scope induced by a type alias declaration, containing the type parameters declared the the alias.
  *
  * Type aliases that do not declare type parameters have no scope object.
  */
@@ -1662,14 +1662,14 @@ class TypeAliasScope extends @type_alias_scope, Scope {
 }
 
 /**
- * Scope induced by a mapped type expression, containing the type parameter declared as part of the type.
+ * A scope induced by a mapped type expression, containing the type parameter declared as part of the type.
  */
 class MappedTypeScope extends @mapped_type_scope, Scope {
   override string toString() { result = "mapped type scope" }
 }
 
 /**
- * Scope induced by an enum declaration, containing the names of its enum members.
+ * A scope induced by an enum declaration, containing the names of its enum members.
  *
  * Initializers of enum members are resolved in this scope since they can reference
  * previously-defined enum members by their unqualified name.
@@ -2637,7 +2637,7 @@ class TypeofType extends Type, @typeof_type {
 }
 
 /**
- * One of two values indicating if a signature is a function or constructor signature.
+ * A value indicating if a signature is a function or constructor signature.
  */
 class SignatureKind extends string {
   SignatureKind() { this = "function" or this = "constructor" }

javascript/ql/lib/semmle/javascript/dataflow/TypeTracking.qll

@@ -15,7 +15,7 @@ private import semmle.javascript.internal.CachedStages
 private newtype TTypeTracker = MkTypeTracker(Boolean hasCall, OptionalPropertyName prop)
 
 /**
- * Summary of the steps needed to track a value to a given dataflow node.
+ * A summary of the steps needed to track a value to a given dataflow node.
  *
  * This can be used to track objects that implement a certain API in order to
  * recognize calls to that API. Note that type-tracking does not by itself provide a
@@ -182,7 +182,7 @@ module TypeTracker {
 private newtype TTypeBackTracker = MkTypeBackTracker(Boolean hasReturn, OptionalPropertyName prop)
 
 /**
- * Summary of the steps needed to back-track a use of a value to a given dataflow node.
+ * A summary of the steps needed to back-track a use of a value to a given dataflow node.
  *
  * This can be used to track callbacks that are passed to a certain API call, and are
  * therefore expected to be called with a certain type of value.

javascript/ql/lib/semmle/javascript/frameworks/Babel.qll

@@ -49,7 +49,7 @@ module Babel {
   }
 
   /**
-   * Configuration object for a Babel plugin.
+   * A configuration object for a Babel plugin.
    */
   class Plugin extends JSONValue {
     Config cfg;

javascript/ql/lib/semmle/javascript/frameworks/Cheerio.qll

@@ -29,7 +29,7 @@ module Cheerio {
   DataFlow::SourceNode cheerioRef() { result = cheerioRef(DataFlow::TypeTracker::end()) }
 
   /**
-   * Creation of `cheerio` object, a collection of virtual DOM elements
+   * A creation of `cheerio` object, a collection of virtual DOM elements
    * with an interface similar to that of a jQuery object.
    */
   class CheerioObjectCreation extends DataFlow::SourceNode instanceof CheerioObjectCreation::Range {
@@ -88,7 +88,7 @@ module Cheerio {
   }
 
   /**
-   * Definition of a DOM attribute through `cheerio`.
+   * A definition of a DOM attribute through `cheerio`.
    */
   class AttributeDef extends DOM::AttributeDefinition {
     DataFlow::CallNode call;
@@ -105,7 +105,7 @@ module Cheerio {
   }
 
   /**
-   * XSS sink through `cheerio`.
+   * An XSS sink through `cheerio`.
    */
   class XssSink extends Xss::DomBasedXss::Sink {
     XssSink() {

javascript/ql/lib/semmle/javascript/frameworks/ExpressModules.qll

@@ -16,7 +16,7 @@ module ExpressLibraries {
   }
 
   /**
-   * Header produced by a route handler of the "x-frame-options" module.
+   * A header produced by a route handler of the "x-frame-options" module.
    */
   class XFrameOptionsRouteHandlerHeader extends HTTP::ImplicitHeaderDefinition {
     XFrameOptionsRouteHandlerHeader() { this instanceof XFrameOptionsRouteHandler }
@@ -29,7 +29,7 @@ module ExpressLibraries {
   }
 
   /**
-   * Route handler from the "x-frame-options" module.
+   * A route handler from the "x-frame-options" module.
    */
   class XFrameOptionsRouteHandler extends HTTP::RouteHandler {
     XFrameOptionsRouteHandler() {
@@ -43,7 +43,7 @@ module ExpressLibraries {
   }
 
   /**
-   * Header produced by a route handler of the "frameguard" module.
+   * A header produced by a route handler of the "frameguard" module.
    */
   class FrameGuardRouteHandlerHeader extends HTTP::ImplicitHeaderDefinition {
     FrameGuardRouteHandlerHeader() { this instanceof FrameGuardRouteHandler }
@@ -56,7 +56,7 @@ module ExpressLibraries {
   }
 
   /**
-   * Route handler from the "frameguard" module.
+   * A route handler from the "frameguard" module.
    */
   class FrameGuardRouteHandler extends HTTP::RouteHandler {
     FrameGuardRouteHandler() { this = DataFlow::moduleImport("frameguard").getAnInvocation() }
@@ -68,7 +68,7 @@ module ExpressLibraries {
   }
 
   /**
-   * Header produced by a route handler of the "helmet" module.
+   * A header produced by a route handler of the "helmet" module.
    */
   class HelmetRouteHandlerHeader extends HTTP::ImplicitHeaderDefinition {
     HelmetRouteHandlerHeader() { this instanceof HelmetRouteHandler }
@@ -81,7 +81,7 @@ module ExpressLibraries {
   }
 
   /**
-   * Route handler from the "helmet" module.
+   * A route handler from the "helmet" module.
    */
   class HelmetRouteHandler extends HTTP::RouteHandler {
     HelmetRouteHandler() {

javascript/ql/lib/semmle/javascript/frameworks/Firebase.qll

@@ -179,7 +179,7 @@ module Firebase {
     /** Gets a data flow node holding a `RefBuilder` object. */
     DataFlow::SourceNode ref() { result = refBuilder(DataFlow::TypeTracker::end()) }
 
-    /** Gets a call that registers a listener on a `RefBuilder`, such as `ref.onCreate(...)`. */
+    /** A call that registers a listener on a `RefBuilder`, such as `ref.onCreate(...)`. */
     class RefBuilderListenCall extends DataFlow::MethodCallNode {
       RefBuilderListenCall() {
         this = ref().getAMethodCall() and

javascript/ql/lib/semmle/javascript/frameworks/Next.qll

@@ -44,7 +44,7 @@ module NextJS {
   }
 
   /**
-   * User defined path parameter in `Next.js`.
+   * A user defined path parameter in `Next.js`.
    */
   class NextParams extends RemoteFlowSource {
     NextParams() {

javascript/ql/lib/semmle/javascript/frameworks/Redux.qll

@@ -54,7 +54,7 @@ module Redux {
   }
 
   /**
-   * Creation of a redux store, usually via a call to `createStore`.
+   * A creation of a redux store, usually via a call to `createStore`.
    */
   class StoreCreation extends DataFlow::SourceNode instanceof StoreCreation::Range {
     /** Gets a reference to the store. */
@@ -566,7 +566,7 @@ module Redux {
     }
 
     /**
-     * One of the action creators made by a call to `createActions`:
+     * An action creator made by a call to `createActions`:
      * ```js
      * let { actionOne, actionTwo } = createActions({
      *   ACTION_ONE: (x, y) => { x, y },
@@ -988,7 +988,7 @@ module Redux {
     API::Node useSelector() { result = API::moduleImport("react-redux").getMember("useSelector") }
 
     /**
-     * Step out of a `useSelector` call, such as from `state.x` to the result of `useSelector(state => state.x)`.
+     * A step out of a `useSelector` call, such as from `state.x` to the result of `useSelector(state => state.x)`.
      */
     class UseSelectorStep extends StateStep {
       override predicate step(DataFlow::Node pred, DataFlow::Node succ) {

javascript/ql/lib/semmle/javascript/security/dataflow/StoredXssQuery.qll

@@ -31,7 +31,7 @@ class FileNameSourceAsSource extends Source {
   FileNameSourceAsSource() { this instanceof FileNameSource }
 }
 
-/** User-controlled torrent information, considered as a flow source for stored XSS. */
+/** An instance of user-controlled torrent information, considered as a flow source for stored XSS. */
 class UserControlledTorrentInfoAsSource extends Source {
   UserControlledTorrentInfoAsSource() { this instanceof ParseTorrent::UserControlledTorrentInfo }
 }

javascript/ql/lib/semmle/javascript/security/dataflow/UnsafeJQueryPluginCustomizations.qll

@@ -100,7 +100,7 @@ module UnsafeJQueryPlugin {
   }
 
   /**
-   * Expression of form `isElement(x)`, which sanitizes `x`.
+   * An expression of form `isElement(x)`, which sanitizes `x`.
    */
   class IsElementSanitizer extends TaintTracking::SanitizerGuardNode, DataFlow::CallNode {
     IsElementSanitizer() {
@@ -116,7 +116,7 @@ module UnsafeJQueryPlugin {
   }
 
   /**
-   * Expression like `typeof x.<?> !== "undefined"` or `x.<?>`, which sanitizes `x`, as it is unlikely to be a string afterwards.
+   * An expression like `typeof x.<?> !== "undefined"` or `x.<?>`, which sanitizes `x`, as it is unlikely to be a string afterwards.
    */
   class PropertyPresenceSanitizer extends TaintTracking::SanitizerGuardNode, DataFlow::ValueNode {
     DataFlow::Node input;

javascript/ql/src/Declarations/IneffectiveParameterType.ql

@@ -22,7 +22,7 @@ predicate isCommonPredefinedTypeName(string name) {
 }
 
 /**
- * Any local type declaration, excluding imported names that are not explicitly used as types.
+ * A local type declaration, excluding imported names that are not explicitly used as types.
  */
 class DefiniteTypeDecl extends TypeDecl {
   DefiniteTypeDecl() {

javascript/ql/src/Expressions/ImplicitOperandConversion.ql

@@ -56,8 +56,8 @@ abstract class ImplicitConversionWithWhitelist extends ImplicitConversion {
 }
 
 /**
- * Property names in `in` expressions are converted to strings,
- * so they should be strings or numbers.
+ * A property name in an `in` expression that is converted to string,
+ * so it should be a string or number.
  */
 class PropertyNameConversion extends ImplicitConversionWithWhitelist {
   PropertyNameConversion() { this.asExpr() = parent.(InExpr).getLeftOperand() }
@@ -68,8 +68,8 @@ class PropertyNameConversion extends ImplicitConversionWithWhitelist {
 }
 
 /**
- * Property names in index expressions are converted to strings,
- * so they should be Booleans, strings or numbers.
+ * A property name in an index expression that is converted to string,
+ * so it should be Boolean, string or number.
  */
 class IndexExprConversion extends ImplicitConversionWithWhitelist {
   IndexExprConversion() { this.asExpr() = parent.(IndexExpr).getIndex() }
@@ -82,7 +82,7 @@ class IndexExprConversion extends ImplicitConversionWithWhitelist {
 }
 
 /**
- * Expressions that are interpreted as objects shouldn't be primitive values.
+ * An expression that is interpreted as an object, and therefore shouldn't be a primitive value.
  */
 class ObjectConversion extends ImplicitConversionWithWhitelist {
   ObjectConversion() {
@@ -107,8 +107,8 @@ class ConstructorConversion extends ImplicitConversionWithWhitelist {
 }
 
 /**
- * Operands of relational operators are converted to strings or numbers,
- * and hence should be strings, numbers or Dates.
+ * An operand of an relational comparison that is converted to string or number,
+ * and hence should be a string, number or Date.
  */
 class RelationalOperandConversion extends ImplicitConversionWithWhitelist {
   RelationalOperandConversion() { parent instanceof RelationalComparison }
@@ -121,8 +121,8 @@ class RelationalOperandConversion extends ImplicitConversionWithWhitelist {
 }
 
 /**
- * Operands of arithmetic and bitwise operations are converted to numbers,
- * so they should be Booleans, numbers or Dates.
+ * An operand of arithmetic and bitwise operations that is converted to a number,
+ * so it should be a Boolean, number or Date.
  */
 class NumericConversion extends ImplicitConversion {
   NumericConversion() {
@@ -156,7 +156,7 @@ abstract class NullOrUndefinedConversion extends ImplicitConversion {
 }
 
 /**
- * Operands of `+` or `+=` are converted to strings or numbers, and hence
+ * An operand of `+` or `+=` that is converted to string or number, and hence
  * should not be `null` or `undefined`.
  */
 class PlusConversion extends NullOrUndefinedConversion {
@@ -186,7 +186,7 @@ class PlusConversion extends NullOrUndefinedConversion {
 }
 
 /**
- * Template literal elements are converted to strings, and hence should not
+ * A template literal element that is converted to a string, and hence should not
  * be `null` or `undefined`.
  */
 class TemplateElementConversion extends NullOrUndefinedConversion {

javascript/ql/src/Security/CWE-915/PrototypePollutingFunction.ql

@@ -193,7 +193,7 @@ string unsafePropName() {
 }
 
 /**
- * Flow label representing an unsafe property name, or an object obtained
+ * A flow label representing an unsafe property name, or an object obtained
  * by using such a property in a dynamic read.
  */
 class UnsafePropLabel extends FlowLabel {
@@ -295,7 +295,7 @@ class PropNameTracking extends DataFlow::Configuration {
 }
 
 /**
- * Sanitizer guard of form `x === "__proto__"` or `x === "constructor"`.
+ * A sanitizer guard of form `x === "__proto__"` or `x === "constructor"`.
  */
 class DenyListEqualityGuard extends DataFlow::LabeledBarrierGuardNode, ValueNode {
   override EqualityTest astNode;
@@ -355,7 +355,7 @@ class HasOwnPropertyGuard extends DataFlow::BarrierGuardNode, CallNode {
 }
 
 /**
- * Sanitizer guard for `key in dst`.
+ * A sanitizer guard for `key in dst`.
  *
  * Since `"__proto__" in obj` and `"constructor" in obj` is true for most objects,
  * this is seen as a sanitizer for `key` in the false outcome.
@@ -374,7 +374,7 @@ class InExprGuard extends DataFlow::BarrierGuardNode, DataFlow::ValueNode {
 }
 
 /**
- * Sanitizer guard for `instanceof` expressions.
+ * A sanitizer guard for `instanceof` expressions.
  *
  * `Object.prototype instanceof X` is never true, so this blocks the `__proto__` label.
  *