/*
 * Copyright 2020 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package androidx.room;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * When present, {@link RewriteQueriesToDropUnusedColumns} annotation will cause Room to
 * rewrite your {@link Query} methods such that only the columns that are used in the response are
 * queried from the database.
 * <p>
 * This annotation is useful if you don't need all columns returned in a query but also don't
 * want to spell out their names in the query projection.
 * <p>
 * For example, if you have a {@code User} class with 10 fields and want to return only
 * the {@code name} and {@code lastName} fields in a POJO, you could write the query like this:
 *
 * <pre>
 * {@literal @}Dao
 * interface MyDao {
 *     {@literal @}Query("SELECT * FROM User")
 *     public List<NameAndLastName> getAll();
 * }
 * class NameAndLastName {
 *     public String name;
 *     public String lastName;
 * }
 * </pre>
 * <p>
 * Normally, Room would print a {@link RoomWarnings#CURSOR_MISMATCH} warning since the query result
 * has additional columns that are not used in the response. You can annotate the method with
 * {@link RewriteQueriesToDropUnusedColumns} to inform Room to rewrite your query at compile time to
 * avoid fetching extra columns.
 * <pre>
 * {@literal @}Dao
 * interface MyDao {
 *     {@literal @}RewriteQueriesToDropUnusedColumns
 *     {@literal @}Query("SELECT * FROM User")
 *     public List<NameAndLastName> getAll();
 * }
 * </pre>
 * At compile time, Room will convert this query to {@code SELECT name, lastName FROM (SELECT *
 * FROM User)} which gets flattened by <b>Sqlite</b> to {@code SELECT name, lastName FROM User}.
 * <p>
 * When the annotation is used on a {@link Dao} method annotated with {@link Query}, it will only
 * affect that query. You can put the annotation on the {@link Dao} annotated class/interface or
 * the {@link Database} annotated class where it will impact all methods in the dao / database
 * respectively.
 * <p>
 * Note that Room will not rewrite the query if it has multiple columns that have the same name as
 * it does not yet have a way to distinguish which one is necessary.
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.CLASS)
public @interface RewriteQueriesToDropUnusedColumns {
}

@@ -1430,33 +1430,32 @@
      %7B@literal @
-%7D
 Query(%22SELECT * 
@@ -1461,32 +1461,33 @@
  FROM User%22)
+%7D
 %0A *     
 public List%3C
@@ -1466,32 +1466,42 @@
  User%22)%7D%0A *     
+%7B@literal 
 public List%3CName
@@ -1514,32 +1514,33 @@
 tName%3E getAll();
+%7D
 %0A * %7D%0A * class N
@@ -2031,17 +2031,16 @@
 iteral @
-%7D
 RewriteQ
@@ -2064,16 +2064,17 @@
 dColumns
+%7D
 %0A *     
@@ -2084,17 +2084,16 @@
 iteral @
-%7D
 Query(%22S
@@ -2111,24 +2111,25 @@
 M User%22)
+%7D
 %0A *     
 public L
@@ -2116,24 +2116,34 @@
 r%22)%7D%0A *     
+%7B@literal 
 public List%3C
@@ -2168,16 +2168,17 @@
 etAll();
+%7D
 %0A * %7D%0A *

Fix Javadoc so that List<NameAndLastName> is not considered to be HTML