@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.
Methods
public abstract String name() default "" | The key this attribute writes, when it is not the group’s prefix followed by the attribute name. |
public abstract String valuePattern() default "" | A regular expression the value must match, or "" for no check. |
public abstract HintKind kind() default HintKind.DEFAULT | What kind of string this is, when the attribute’s Java type does not say. |
public abstract boolean appendable() default false | Whether a cn1lib may append to this hint rather than replace it. |
public abstract String separator() default "" | What a list’s values are joined with on the wire. |
public abstract String platform() default "" | The platform this hint applies to, for the guide’s table. |
public abstract String aliasOf() default "" | The hint this one is a deprecated second spelling of. |
public abstract String deprecated() default "" | Why this hint is deprecated, and what to use instead. |
public abstract boolean external() default false | Documented here but read only by the build service, so nothing in this repository consumes it. |
public abstract boolean enterpriseOnly() default false | Available only to enterprise accounts. |
public abstract String link() default "" | Further reading, for the guide’s table. |
Method details
name
public abstract String name() default ""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.
valuePattern
public abstract String valuePattern() default ""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.
kind
public abstract HintKind kind() default HintKind.DEFAULTWhat 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.
appendable
public abstract boolean appendable() default falseWhether 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.
separator
public abstract String separator() default ""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.
platform
public abstract String platform() default ""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.
aliasOf
public abstract String aliasOf() default ""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.
deprecated
public abstract String deprecated() default ""external
public abstract boolean external() default falseenterpriseOnly
public abstract boolean enterpriseOnly() default falselink
public abstract String link() default ""