more comments

src/java/org/apache/cassandra/db/filter/ColumnFilter.java

@@ -297,14 +297,16 @@ public static ColumnFilter selection(TableMetadata metadata,
     }
 
     /**
-     * The columns that needs to be fetched internally for this filter.
+     * The columns that needs to be fetched internally.  See FetchingStrategy for why this is almost
+     * always a superset of the queried columns.
      *
      * @return the columns to fetch for this filter.
      */
     public abstract RegularAndStaticColumns fetchedColumns();
 
     /**
-     * The columns actually queried by the user.
+     * The columns needed to process the query, including selected columns, ordering columns,
+     * restriction (predicate) columns, and synthetic columns.
      * <p>
      * Note that this is in general not all the columns that are fetched internally (see {@link #fetchedColumns}).
      */
@@ -621,9 +623,7 @@ private SortedSetMultimap<ColumnIdentifier, ColumnSubselection> buildSubSelectio
      */
     public static class WildCardColumnFilter extends ColumnFilter
     {
-        /**
-         * The queried and fetched columns.
-         */
+        // for wildcards, there is no distinction between fetched and queried because queried is already "everything"
         private final RegularAndStaticColumns fetchedAndQueried;
 
         /**
@@ -741,14 +741,9 @@ public static class SelectionColumnFilter extends ColumnFilter
     {
         public final FetchingStrategy fetchingStrategy;
 
-        /**
-         * The selected columns
-         */
+        // Materializes the columns required to implement queriedColumns() and fetchedColumns(),
+        // see the comments to superclass's methods
         private final RegularAndStaticColumns queried;
-
-        /**
-         * The columns that need to be fetched to be able
-         */
         private final RegularAndStaticColumns fetched;
 
         private final SortedSetMultimap<ColumnIdentifier, ColumnSubselection> subSelections; // can be null