Document Arel.sql

activerecord/lib/arel.rb

@@ -24,22 +24,29 @@
 require "arel/delete_manager"
 require "arel/nodes"
 
-module Arel # :nodoc: all
+module Arel
   VERSION = "10.0.0"
 
+  # Wrap a known-safe SQL string for passing to query methods, e.g.
+  #
+  #   Post.order(Arel.sql("length(title)")).last
+  #
+  # Great caution should be taken to avoid SQL injection vulnerabilities.
+  # This method should not be used with unsafe values such as request
+  # parameters or model attributes.
   def self.sql(raw_sql)
     Arel::Nodes::SqlLiteral.new raw_sql
   end
 
-  def self.star
+  def self.star # :nodoc:
     sql "*"
   end
 
-  def self.arel_node?(value)
+  def self.arel_node?(value) # :nodoc:
     value.is_a?(Arel::Node) || value.is_a?(Arel::Attribute) || value.is_a?(Arel::Nodes::SqlLiteral)
   end
 
-  def self.fetch_attribute(value)
+  def self.fetch_attribute(value) # :nodoc:
     case value
     when Arel::Nodes::Between, Arel::Nodes::In, Arel::Nodes::NotIn, Arel::Nodes::Equality, Arel::Nodes::NotEqual, Arel::Nodes::LessThan, Arel::Nodes::LessThanOrEqual, Arel::Nodes::GreaterThan, Arel::Nodes::GreaterThanOrEqual
       yield value.left.is_a?(Arel::Attributes::Attribute) ? value.left : value.right
@@ -47,5 +54,5 @@ def self.fetch_attribute(value)
   end
 
   ## Convenience Alias
-  Node = Arel::Nodes::Node
+  Node = Arel::Nodes::Node # :nodoc:
 end

railties/lib/rails/api/task.rb

@@ -18,6 +18,7 @@ class Task < RDoc::Task
           include: %w(
             README.rdoc
             lib/active_record/**/*.rb
+            lib/arel.rb
           )
         },