# Annotation Type Hint

@Retention(CLASS) @Target({METHOD,ANNOTATION_TYPE}) public @interface Hint

What a build hint attribute is, beyond what its Java signature already says.

The attribute's type, its name and its enum's constants are the compiler's business and are not restated here. This carries only what javac cannot infer: the wire key when it differs from the attribute name, the prose the developer guide and the Settings editor show, and the handful of facts about how the builders read the value.

The annotation's own `default` clause is deliberately NOT the build server's default, and nothing here records that either. A hint is written only where the developer set it, so the clause has no meaning at runtime -- see `HintUnset` for what the default clause does say.

ANNOTATION_TYPE rather than TYPE. This describes a build hint annotation or one of its members, and both are annotation declarations. Allowing TYPE let `@Hint(name = "ios.pods")` be written straight onto an application class, where it compiles, sets nothing, and reports nothing -- which is the exact silence these annotations exist to remove.

- ## Optional Element Summary

  Optional Elements
  Modifier and Type
  Optional Element
  Description
  `String`
  `aliasOf`
  The hint this one is a deprecated second spelling of.
  `boolean`
  `appendable`
  Whether a cn1lib may append to this hint rather than replace it.
  `String`
  `deprecated`
  Why this hint is deprecated, and what to use instead.
  `boolean`
  `enterpriseOnly`
  Available only to enterprise accounts.
  `boolean`
  `external`
  Documented here but read only by the build service, so nothing in this repository consumes it.
  `HintKind`
  `kind`
  What kind of string this is, when the attribute's Java type does not say.
  `String`
  `link`
  Further reading, for the guide's table.
  `String`
  `name`
  The key this attribute writes, when it is not the group's prefix followed by the attribute name.
  `String`
  `platform`
  The platform this hint applies to, for the guide's table.
  `String`
  `separator`
  What a list's values are joined with on the wire.
  `String`
  `valuePattern`
  A regular expression the value must match, or "" for no check.

- ## Element Details

  - ### name

    String name

    The key this attribute writes, when it is not the group's prefix followed by the attribute name.

    `android.min_sdk_version` is not `minSdkVersion`, and the builders are the authority on the spelling.

    Default:
      `""`

  - ### valuePattern

    String valuePattern

    A regular expression the value must match, or "" for no check.

    For the hints whose type cannot express their shape. `String` says nothing about `ios.interface_orientation`, whose value is a colon separated list of four known constants -- and a misspelled one does not fail, it just fails to match, so the builder keeps every orientation and the app ships rotating in directions it was told not to.

    Checked by the annotation processor against the value that is about to be written, so it fails the build that declared it rather than the device that runs it. `java.util.regex` syntax, anchored implicitly: the WHOLE value must match.

    Default:
      `""`

  - ### kind

    HintKind kind

    What kind of string this is, when the attribute's Java type does not say.

    The editor picks its control from this: a version field, a masked field for a secret, a multi-line box for an XML fragment.

    Default:
      `DEFAULT`

  - ### appendable

    boolean appendable

    Whether a cn1lib may append to this hint rather than replace it.

    Separate from `separator()` because the delimiter can legitimately be empty: the XML fragment family -- `android.xpermissions` and friends -- is appended to with nothing between the pieces, which is not the same as a hint no library can contribute to.

    Default:
      `false`

  - ### separator

    String separator

    What a list's values are joined with on the wire.

    A cn1lib appends onto the same key, so this has to match what the builder splits on -- `ios.pods` is comma delimited and `ios.add_libs` semicolon delimited.

    Default:
      `""`

  - ### platform

    String platform

    The platform this hint applies to, for the guide's table.

    On the annotation TYPE this is the default for every attribute in it, which is where it belongs: every hint in `@Android` is an Android hint, and saying so on each of the twenty-four was noise that could also be got wrong. An attribute states it only to disagree -- `@OnDeviceDebug` spans two platforms and each of its attributes says which.

    Default:
      `""`

  - ### aliasOf

    String aliasOf

    The hint this one is a deprecated second spelling of.

    Both names denote ONE effective setting -- the builder reads `android.captureRecord` and then lets `and.captureRecord` override it -- so conflict detection has to collapse them.

    Default:
      `""`

  - ### deprecated

    String deprecated
    Why this hint is deprecated, and what to use instead.
    Default:
      `""`

  - ### external

    boolean external
    Documented here but read only by the build service, so nothing in this repository consumes it.
    Default:
      `false`

  - ### enterpriseOnly

    boolean enterpriseOnly
    Available only to enterprise accounts.
    Default:
      `false`

  - ### link

    String link
    Further reading, for the guide's table.
    Default:
      `""`