 /// [**Experimental**](http://github.com/groue/GRDB.swift#what-are-experimental-features)
 ///
-/// SQLGenerationContext is responsible for preventing SQL injection and
-/// disambiguating table names when GRDB generates SQL queries.
+/// SQLGenerationContext support for SQL generation:
+///
+/// - It provides a database connection so that request elements can perform
+///   database introspection in order to build their SQL representation.
+///
+/// - It provides an "argumens sink" where request elements can dump database
+///   values, in order to prevent SQL injection.
+///
+/// - It provides unique table aliases in order to disambiguates table names
+///   and columns.
 ///
 /// :nodoc:
 public struct SQLGenerationContext {
+    /// A database connection so that request elements can perform database
+    /// introspection in order to build their SQL representation.
     let db: Database
+    
+    /// An argumens sink where request elements can dump database values, in
+    /// order to prevent SQL injection.
+    let argumentsSink: StatementArgumentsSink
+    
+    /// All arguments gathered so far
     var arguments: StatementArguments { argumentsSink.arguments }
-    let argumentsSink: StatementArgumentsSink
+    
     private var resolvedNames: [TableAlias: String]
-    private var qualifierNeeded: Bool
+    private var qualifiesColumnsWithTable: Bool
         
     /// Used for literal generation
     static func sqlLiteralContext(

            db: db,
            argumentsSink: argumentsSink,
            resolvedNames: aliases.resolvedNames,
            qualifierNeeded: aliases.count > 1)
    }
    
    /// Returns whether arguments could be appended.

        if alias.hasUserName {
            return alias.identityName
        }
        if qualifiesColumnsWithTable == false {
            return nil
        }
        return resolvedName(for: alias)
