Ruby: Add missing documentation

Author: hmac

ruby/ql/lib/codeql/ruby/frameworks/ActionController.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides modeling for the `ActionController` library.
+ */
+
 private import codeql.ruby.AST
 private import codeql.ruby.Concepts
 private import codeql.ruby.controlflow.CfgNodes
@@ -66,10 +70,14 @@ class ActionControllerActionMethod extends Method, HTTP::Server::RequestHandler:
   /** Gets a call to render from within this method. */
   RenderCall getARenderCall() { result.getParent+() = this }
 
-  // TODO: model the implicit render call when a path through the method does
-  // not end at an explicit render or redirect
-  /** Gets the controller class containing this method. */
-  ActionControllerControllerClass getControllerClass() { result = controllerClass }
+  /**
+   * Gets the controller class containing this method.
+   */
+  ActionControllerControllerClass getControllerClass() {
+    // TODO: model the implicit render call when a path through the method does
+    // not end at an explicit render or redirect
+    result = controllerClass
+  }
 
   /**
    * Gets a route to this handler, if one exists.
@@ -101,6 +109,9 @@ private class ActionControllerContextCall extends MethodCall {
     this.getEnclosingModule() = controllerClass
   }
 
+  /**
+   * Gets the controller class containing this method.
+   */
   ActionControllerControllerClass getControllerClass() { result = controllerClass }
 }
 

ruby/ql/lib/codeql/ruby/frameworks/ActionView.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides modeling for the `ActionView` library.
+ */
+
 private import codeql.ruby.AST
 private import codeql.ruby.Concepts
 private import codeql.ruby.controlflow.CfgNodes
@@ -6,6 +10,9 @@ private import codeql.ruby.dataflow.RemoteFlowSources
 private import codeql.ruby.ast.internal.Module
 private import ActionController
 
+/**
+ * Holds if this AST node is in a context where `ActionView` methods are available.
+ */
 predicate inActionViewContext(AstNode n) {
   // Within a template
   n.getLocation().getFile() instanceof ErbFile
@@ -33,6 +40,9 @@ abstract class HtmlEscapeCall extends MethodCall {
   HtmlEscapeCall() { this.getMethodName() = ["html_escape", "html_escape_once", "h"] }
 }
 
+/**
+ * A call to a Rails method that escapes HTML.
+ */
 class RailsHtmlEscaping extends Escaping::Range, DataFlow::CallNode {
   RailsHtmlEscaping() { this.asExpr().getExpr() instanceof HtmlEscapeCall }
 
@@ -55,6 +65,9 @@ private class ActionViewContextCall extends MethodCall {
     inActionViewContext(this)
   }
 
+  /**
+   * Holds if this call is located inside an ERb template.
+   */
   predicate isInErbFile() { this.getLocation().getFile() instanceof ErbFile }
 }
 
@@ -132,6 +145,9 @@ private class ActionViewRenderToCall extends ActionViewContextCall, RenderToCall
 class LinkToCall extends ActionViewContextCall {
   LinkToCall() { this.getMethodName() = "link_to" }
 
+  /**
+   * Gets the path argument to the call.
+   */
   Expr getPathArgument() {
     // When `link_to` is called with a block, it uses the first argument as the
     // path, and otherwise the second argument.

ruby/ql/lib/codeql/ruby/frameworks/ActiveRecord.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides modeling for the `ActiveRecord` library.
+ */
+
 private import codeql.ruby.AST
 private import codeql.ruby.Concepts
 private import codeql.ruby.controlflow.CfgNodes
@@ -183,6 +187,9 @@ class PotentiallyUnsafeSqlExecutingMethodCall extends ActiveRecordModelClassMeth
     )
   }
 
+  /**
+   * Gets the SQL fragment argument of this method call.
+   */
   Expr getSqlFragmentSinkArgument() { result = sqlFragmentExpr }
 }
 
@@ -208,6 +215,9 @@ class ActiveRecordSqlExecutionRange extends SqlExecution::Range {
  */
 abstract class ActiveRecordModelInstantiation extends OrmInstantiation::Range,
   DataFlow::LocalSourceNode {
+  /**
+   * Gets the `ActiveRecordModelClass` that this instance belongs to.
+   */
   abstract ActiveRecordModelClass getClass();
 
   bindingset[methodName]

ruby/ql/lib/codeql/ruby/frameworks/ActiveStorage.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides modeling for the `ActiveStorage` library.
+ */
+
 private import codeql.ruby.AST
 private import codeql.ruby.ApiGraphs
 private import codeql.ruby.Concepts

ruby/ql/lib/codeql/ruby/frameworks/Core.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides modeling for the Ruby core libraries.
+ */
+
 private import codeql.ruby.Concepts
 private import codeql.ruby.DataFlow
 private import codeql.ruby.dataflow.FlowSummary

ruby/ql/lib/codeql/ruby/frameworks/XmlParsing.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides modeling for common XML libraries.
+ */
+
 private import codeql.ruby.Concepts
 private import codeql.ruby.AST
 private import codeql.ruby.DataFlow
@@ -70,11 +74,26 @@ private newtype TFeature =
   TNONET() or
   TDTDLOAD()
 
+/**
+ * A representation of XML features that can be enabled or disabled.
+ * - `TNOENT`: Enables substitution of external entities.
+ * - `TNONET`: Disables network access.
+ * - `TDTDLOAD`: Disables loading of DTDs.
+ */
 class Feature extends TFeature {
+  /**
+   * Gets the bitmask value for this feature.
+   */
   abstract int getValue();
 
+  /**
+   * Gets the string representation of this feature.
+   */
   string toString() { result = this.getConstantName() }
 
+  /**
+   * Gets the name of this feature.
+   */
   abstract string getConstantName();
 }
 

ruby/ql/lib/codeql/ruby/frameworks/core/BasicObject.qll

@@ -1,7 +1,14 @@
+/**
+ * Provides modeling for the `BasicObject` class.
+ */
+
 private import codeql.ruby.AST
 private import codeql.ruby.Concepts
 private import codeql.ruby.DataFlow
 
+/**
+ * Provides modeling for the `BasicObject` class.
+ */
 module BasicObject {
   /**
    * An instance method on `BasicObject`, which is available to all classes.
@@ -10,6 +17,9 @@ module BasicObject {
     BasicObjectInstanceMethodCall() { this.getMethodName() = basicObjectInstanceMethodName() }
   }
 
+  /**
+   * Gets the name of an instance method on `BasicObject`.
+   */
   string basicObjectInstanceMethodName() {
     result in [
         "equal?", "instance_eval", "instance_exec", "method_missing", "singleton_method_added",

ruby/ql/lib/codeql/ruby/frameworks/core/Kernel.qll

@@ -1,3 +1,7 @@
+/**
+ * Provides modeling for the `Kernel` module.
+ */
+
 private import codeql.ruby.AST
 private import codeql.ruby.ApiGraphs
 private import codeql.ruby.CFG
@@ -6,7 +10,7 @@ private import codeql.ruby.DataFlow
 private import codeql.ruby.dataflow.FlowSummary
 private import codeql.ruby.dataflow.internal.DataFlowDispatch
 
-/** Modeling for the `Kernel` class. */
+/** Provides modeling for the `Kernel` class. */
 module Kernel {
   /**
    * The `Kernel` module is included by the `Object` class, so its methods are available

ruby/ql/lib/codeql/ruby/frameworks/core/Module.qll

@@ -1,7 +1,14 @@
+/**
+ * Provides modeling for the `Module` class.
+ */
+
 private import codeql.ruby.AST
 private import codeql.ruby.Concepts
 private import codeql.ruby.DataFlow
 
+/**
+ * Provides modeling for the `Module` class.
+ */
 module Module {
   /**
    * A call to `Module#module_eval`, which executes its first argument as Ruby code.

ruby/ql/lib/codeql/ruby/frameworks/core/Object.qll

@@ -1,5 +1,12 @@
+/**
+ * Provides modeling for the `Object` class.
+ */
+
 private import codeql.ruby.AST
 
+/**
+ * Provides modeling for the `Object` class.
+ */
 module Object {
   /**
    * An instance method on `Object`, which is available to all classes except `BasicObject`.
@@ -8,6 +15,9 @@ module Object {
     ObjectInstanceMethodCall() { this.getMethodName() = objectInstanceMethodName() }
   }
 
+  /**
+   * Gets the name of an `Object` instance method.
+   */
   string objectInstanceMethodName() {
     result in [
         "!~", "<=>", "===", "=~", "callable_methods", "define_singleton_method", "display",