AppFunctionInstruction

@Retention(value = AnnotationRetention.BINARY)
@Target(allowedTargets = [AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY, AnnotationTarget.VALUE_PARAMETER, AnnotationTarget.TYPE, AnnotationTarget.CLASS])
annotation AppFunctionInstruction

Provides an explicit instruction for an AppFunction, an AppFunctionSignature, or an AppFunctionSerializable and their respective components.

Using this annotation will provide instructions to agents that receive the androidx.appfunctions.metadata.AppFunctionMetadata to understand how to use the AppFunction.

It can be applied to the following targets:

• A function annotated with @AppFunction: Sets the general description of the AppFunction.

@AppFunction
@AppFunctionInstruction("Creates a new calendar event.")
fun createEvent(title: String)

• A parameter of an @AppFunction: Sets the description for that specific parameter.

@AppFunction
fun getWeather(
  context: AppFunctionContext,
  @AppFunctionInstruction("The city to get the weather for, e.g., 'San Francisco'.")
  city: String
)

• The return type of @AppFunction: Sets the description for the response.

@AppFunction
fun calculateDistance(
    context: AppFunctionContext,
    start: Location,
    destination: Location
): @AppFunctionInstruction("The distance in miles.") Float

• Components of an @AppFunctionSignature: Works in a similar way as for an @AppFunction by setting the description for the abstract method, its parameters, or its return type.

@AppFunctionSignature
fun interface EnableCaptionsSignature {
    @AppFunctionInstruction("Enables closed captions for media playback.")
    suspend fun enableCaptions(
        @AppFunctionInstruction("The language code for the captions (e.g., 'en', 'es').")
        language: String,
        @AppFunctionInstruction("Whether to display a dark background behind the caption text.")
        showBackground: Boolean
    ): @AppFunctionInstruction("Whether the captions were successfully enabled.") Boolean
}

• A class annotated with @AppFunctionSerializable: Sets the description of the data type.

@AppFunctionSerializable
@AppFunctionInstruction("Represents a geographical location.")
class Location(val lat: Double, val lng: Double)

• A property of an @AppFunctionSerializable class: Sets the description for that property.

@AppFunctionSerializable
class UserProfile(
    @AppFunctionInstruction("The user's display name.")
    val displayName: String
)

When a component has opted-in to KDoc extraction (e.g., using isDescribedByKDoc = true), the instruction provided by this annotation will take precedence, overriding the KDoc description for the component in the generated metadata. For example, if the annotation is applied on the parameter, it would override the parameter's KDoc.

Summary

AppFunctionInstruction(instruction: String)

val instruction: String