एनोटेशन की मदद से कोड की जांच को बेहतर बनाना

कोड की जांच करने वाले टूल, जैसे कि लिंट का इस्तेमाल करके, समस्याओं को हल कर सकते हैं और अपने कोड को बेहतर बना सकते हैं, लेकिन निरीक्षण टूल सिर्फ़ इतना ही अनुमान लगा सकते हैं. Android के रिसॉर्स आईडी, उदाहरण के लिए, स्ट्रिंग, ग्राफ़िक, कलर, और अन्य तरह के रिसॉर्स की पहचान करने के लिए, int का इस्तेमाल करें. इसलिए, जांच करने वाले टूल यह नहीं बता सकते कि आपने स्ट्रिंग के लिए ऐसा संसाधन कब चुना जो आपके पास होना चाहिए एक रंग दर्ज किया गया. इसका मतलब है कि हो सकता है कि आपका ऐप्लिकेशन गलत तरीके से रेंडर हो रहा हो या बिलकुल भी न चल पाए, भले ही, आपने कोड की जांच की हो.

एनोटेशन की मदद से, कोड की जांच करने वाले टूल को संकेत दिया जा सकता है, जैसे कि लिंट कोड से जुड़ी अन्य सामान्य समस्याएं हो सकती हैं. एनोटेशन को ऐसे मेटाडेटा टैग के तौर पर जोड़ा जाता है जिसे वैरिएबल से जोड़ा जाता है, पैरामीटर और वैल्यू रिटर्न का इस्तेमाल करके, तरीके से रिटर्न वैल्यू, पास किए गए पैरामीटर, लोकल वैरिएबल और फ़ील्ड शामिल करें. कोड जांचने वाले टूल के साथ इस्तेमाल किए जाने पर, एनोटेशन की मदद से, इस तरह की समस्याओं का पता लगाया जा सकता है शून्य पॉइंटर के अपवाद और रिसॉर्स टाइप से जुड़े विवाद.

Android, कई एनोटेशन के साथ Jetpack एनोटेशन लाइब्रेरी. आप यहां से लाइब्रेरी ऐक्सेस कर सकते हैं: androidx.annotation पैकेज.

ध्यान दें: अगर कोई मॉड्यूल किसी एनोटेशन प्रोसेसर पर निर्भर है, तो Kotlin के लिए, आपको kapt या ksp डिपेंडेंसी कॉन्फ़िगरेशन का इस्तेमाल करना होगा या Java के लिए उसे जोड़ने के लिए annotationProcessor डिपेंडेंसी कॉन्फ़िगरेशन निर्भर है.

अपने प्रोजेक्ट में एनोटेशन जोड़ना

अपने प्रोजेक्ट में एनोटेशन चालू करने के लिए, androidx.annotation:annotation जोड़ें निर्भर नहीं करता है. कोड चलाते समय, जोड़े गए एनोटेशन की जांच की जाती है की जांच करें या lint टास्क पूरा करें.

Jetpack एनोटेशन लाइब्रेरी डिपेंडेंसी जोड़ें

Jetpack एनोटेशन लाइब्रेरी यहां पब्लिश की गई है Google की Maven रिपॉज़िटरी. अपने प्रोजेक्ट में Jetpack Anotations लाइब्रेरी जोड़ने के लिए, ये चीज़ें शामिल करें अपने build.gradle के dependencies ब्लॉक में लाइन या build.gradle.kts फ़ाइल:

Kotlin

dependencies {
    implementation("androidx.annotation:annotation:1.8.1")
}

ग्रूवी

dependencies {
    implementation 'androidx.annotation:annotation:1.8.1'
}

इसके बाद, टूलबार या सिंक की सूचना दिखने पर, अभी सिंक करें पर क्लिक करें.

अगर आप अपनी खुद की लाइब्रेरी मॉड्यूल में एनोटेशन का इस्तेमाल करते हैं, तो एनोटेशन annotations.zip फ़ाइल में, एक्सएमएल फ़ॉर्मैट में Android Archive (AAR) आर्टफ़ैक्ट. इस androidx.annotation डिपेंडेंसी से किसी भी डाउनस्ट्रीम उपयोगकर्ता पर डिपेंडेंसी नहीं मिलती है चुनें.

ध्यान दें: अगर अन्य Jetpack लाइब्रेरी का इस्तेमाल किया जा रहा है, शायद आपको androidx.annotation डिपेंडेंसी जोड़ने की ज़रूरत न पड़े. क्योंकि कई अन्य Jetpack लाइब्रेरी एनोटेशन लाइब्रेरी पर निर्भर करती है, तो हो सकता है कि आपके पास पहले से ही एनोटेशन.

Jetpack डेटा संग्रह स्थान में शामिल एनोटेशन की पूरी सूची देखने के लिए, इनमें से कोई एक देखें Jetpack एनोटेशन लाइब्रेरी संदर्भ हो या फिर ऑटोकंप्लीट सुविधा का इस्तेमाल करके, import androidx.annotation. स्टेटमेंट.

कोड की जांच करें

Android Studio से कोड की जांच शुरू करने के लिए, जिसमें एनोटेशन और लिंट की अपने-आप जांच होने की सुविधा चालू करने के लिए, विश्लेषण करें चुनें > कोड की जांच करें मेन्यू. Android Studio में विरोधी मैसेज दिखाए जाते हैं. इससे, उन संभावित समस्याओं को फ़्लैग किया जा सकता है जहां आपका कोड एनोटेशन और संभावित समाधान सुझाने के लिए.

आप इसे चलाकर भी एनोटेशन लागू कर सकते हैं: कमांड लाइन का इस्तेमाल करके, lint टास्क सेट किया गया. हालांकि, यह समस्याओं को फ़्लैग करने में मददगार हो सकता है इंटीग्रेट करने वाले इंटिग्रेशन सर्वर का इस्तेमाल करने से, lint टास्क में कोई वैल्यू नहीं होनी चाहिए एनोटेशन (नीचे दिए गए सेक्शन में बताए गए हैं); यह काम सिर्फ़ Android Studio से किया जा सकता है. ज़्यादा के लिए लिंट को चालू करने और चलाने के बारे में जानकारी जांच के लिए, लिंट की मदद से अपने कोड को बेहतर बनाना चेक करते हैं.

हालांकि, एनोटेशन के मेल न खाने से चेतावनियां जनरेट होती हैं, लेकिन ये चेतावनियां आपके ऐप्लिकेशन को नहीं रोकतीं कंपाइल करने में मदद की.

शून्य वाले एनोटेशन

वैल्यू शून्य हो सकती है या नहीं, यह लागू करने के लिए Java कोड में, शून्य के तौर पर मार्क किए गए एनोटेशन काम आ सकते हैं. ये Kotlin कोड में कम काम के होते हैं, क्योंकि Kotlin में शून्य होने के नियम बनाए गए हैं. इन नियमों को लागू किया जाता है कंपाइल टाइम.

@Nullable और जोड़ें @NonNull एनोटेशन दिए गए वैरिएबल, पैरामीटर या रिटर्न वैल्यू के शून्य की जांच करने के लिए. @Nullable एनोटेशन से पता चलता है कि वैरिएबल, पैरामीटर या रिटर्न वैल्यू शून्य हो सकती है. @NonNull से ऐसे वैरिएबल, पैरामीटर या रिटर्न वैल्यू के बारे में पता चलता है जो शून्य नहीं हो सकते.

उदाहरण के लिए, अगर शून्य वैल्यू वाले किसी लोकल वैरिएबल को किसी तरीके में पैरामीटर के तौर पर पास किया जाता है उस पैरामीटर के साथ @NonNull एनोटेशन जोड़कर कोड बनाने पर, गैर-शून्य संघर्ष का संकेत देने वाली चेतावनी. साथ ही, किसी ऐसे नतीजा, शून्य जनरेट हुआ है या नहीं, इसकी जांच किए बिना ही @Nullable से मार्क किया गया तरीका शून्य होने की चेतावनी. किसी तरीके की रिटर्न वैल्यू पर ही @Nullable का इस्तेमाल करें होना चाहिए.

नीचे दिए गए उदाहरण में, कार्रवाई में शून्य होने के बारे में बताया गया है. Kotlin के उदाहरण कोड का इस्तेमाल नहीं किया जा सकता @NonNull एनोटेशन, क्योंकि यह जनरेट किए गए बाइटकोड में अपने-आप जुड़ जाता है जब कोई ऐसी वैल्यू दी गई हो जो शून्य न हो. Java के उदाहरण में, @NonNull एनोटेशन का इस्तेमाल किया गया है context और attrs पैरामीटर का इस्तेमाल करके जांच की जा सकती है कि पास की गई पैरामीटर वैल्यू का इस्तेमाल किया गया है या नहीं शून्य नहीं हैं. यह यह भी जांच करता है कि onCreateView() तरीका खाली नहीं दिखाता है:

Kotlin

...
    /** Annotation not used because of the safe-call operator(?)**/
    override fun onCreateView(
            name: String?,
            context: Context,
            attrs: AttributeSet
    ): View? {
        ...
    }
...

Java

import androidx.annotation.NonNull;
...
    /** Add support for inflating the <fragment> tag. **/
    @NonNull
    @Override
    public View onCreateView(String name, @NonNull Context context,
      @NonNull AttributeSet attrs) {
      ...
      }
...

शून्यता का विश्लेषण

Android Studio पर, शून्य की क्षमता का विश्लेषण किया जा सकता है, ताकि यह पता अपने-आप चल सके और अपने कोड में शून्य एनोटेशन डालें. शून्यता वाले विश्लेषण की जांच अपने कोड में मौजूद क्रम के हिसाब से समझौतों का इस्तेमाल करें, ताकि:

• कॉल करने के ऐसे तरीके जिनसे कोई वैल्यू नहीं मिलती.
• वे तरीके जिन्हें शून्य नहीं दिखाना चाहिए.
• फ़ील्ड, लोकल वैरिएबल, और पैरामीटर जैसे वैरिएबल शून्य.
• फ़ील्ड, लोकल वैरिएबल, और पैरामीटर जैसे वैरिएबल, जो ये काम नहीं कर सकते शून्य मान रखें.

इसके बाद, विश्लेषण आपके कैंपेन में शून्य एनोटेशन अपने-आप डाल देता है पता लगाया गया स्थान.

Android Studio में शून्य होने की स्थिति का विश्लेषण करने के लिए, विश्लेषण करें चुनें > न्युलिटी का अनुमान लगाएं. Android Studio, Android @Nullable और @NonNull एनोटेशन को ने आपके कोड में स्थानों का पता लगाया है. शून्य विश्लेषण करने के बाद, यह पुष्टि करना बेहतर होता है कि इंजेक्ट किए गए एनोटेशन.

ध्यान दें: शून्य वाले एनोटेशन जोड़ते समय, ऑटोकंप्लीट की सुविधा IntelliJ का सुझाव दो @Nullable और Android शून्य एनोटेशन के बजाय, @NotNull एनोटेशन और संबंधित लाइब्रेरी को अपने-आप इंपोर्ट कर सकता है. हालांकि, Android Studio लिंट चेकर सिर्फ़ Android शून्य एनोटेशन खोजता है. अपनी एनोटेशन के साथ-साथ, पुष्टि करें कि आपका प्रोजेक्ट Android शून्य एनोटेशन का इस्तेमाल करता है, लिंट चेकर आपको कोड की जांच के दौरान सही तरीके से सूचना दे सकता है.

संसाधन के बारे में जानकारी

रिसॉर्स टाइप की पुष्टि करना मददगार हो सकता है, क्योंकि Android में संसाधनों के रेफ़रंस, जैसे कि ड्रॉ करने लायक और स्ट्रिंग रिसॉर्स, पूर्णांक के तौर पर पास किए जाते हैं.

वह कोड जो किसी पैरामीटर से किसी खास तरह के संसाधन का रेफ़रंस चाहता है, जैसे कि String, को int के अनुमानित संदर्भ प्रकार में पास किया जा सकता है, लेकिन असल में वह किसी अन्य जैसे कि R.string संसाधन.

उदाहरण के लिए, @StringRes एनोटेशन जोड़ें जैसा कि यहां दिखाया गया है, संसाधन पैरामीटर में R.string रेफ़रंस मौजूद होने की जांच करें:

Kotlin

abstract fun setTitle(@StringRes resId: Int)

Java

public abstract void setTitle(@StringRes int resId)

कोड की जांच के दौरान, अगर R.string का रेफ़रंस दिया जाता है, तो एनोटेशन एक चेतावनी जनरेट करता है पैरामीटर में पास नहीं किया जाता है.

@DrawableRes, @DimenRes, @ColorRes, और @InterpolatorRes जैसे अन्य तरह के संसाधनों की व्याख्याएं उसी एनोटेशन फ़ॉर्मैट का इस्तेमाल करके जोड़ा गया हो और कोड की जांच के दौरान चलाया गया हो.

अगर आपका पैरामीटर का इस्तेमाल कई तरह के संसाधन टाइप के साथ किया जा सकता है. हालांकि, एक दी गई फ़ाइल में एक से ज़्यादा रिसॉर्स टाइप के एनोटेशन डाले जा सकते हैं पैरामीटर. @AnyRes का इस्तेमाल करें यह बताने के लिए कि एनोटेशन पैरामीटर किसी भी तरह का R संसाधन हो सकता है.

हालांकि, @ColorRes का इस्तेमाल करके यह बताया जा सकता है कि पैरामीटर एक रंग संसाधन, एक रंग पूर्णांक (RRGGBB या AARRGGBB फ़ॉर्मैट) को कलर रिसॉर्स के तौर पर पहचाना नहीं गया है. इसके बजाय, @ColorInt एनोटेशन का इस्तेमाल इन कामों के लिए करें यह बताता है कि पैरामीटर एक रंग पूर्णांक होना चाहिए. बिल्ड टूल उस गलत कोड को फ़्लैग करेगा जो कलर इंटीजर के बजाय, android.R.color.black जैसे कलर रिसॉर्स आईडी को पास करता है, में जोड़ा जा सकता है.

थ्रेड के बारे में जानकारी

थ्रेड के एनोटेशन से यह पता चलता है कि किसी तरीके को थ्रेड. नीचे दिया गया थ्रेड एनोटेशन समर्थित हैं:

• @MainThread
• @UiThread
• @WorkerThread
• @BinderThread
• @AnyThread

बिल्ड टूल, @MainThread और @UiThread एनोटेशन को आपस में बदला जा सकता है, ताकि आप @UiThread को कॉल कर सकें और @MainThread वाली विधियों से उलटी गिनती की जाती है. हालांकि, यूज़र इंटरफ़ेस (यूआई) के लिए ऐसा किया जा सकता है एक से ज़्यादा व्यू वाले सिस्टम ऐप्लिकेशन के मामले में, मुख्य थ्रेड से अलग थ्रेड होना चाहिए अलग-अलग थ्रेड पर. इसलिए, आपको किसी ऐप्लिकेशन के व्यू हैरारकी (व्यू और व्यू ग्रुप के लेआउट का क्रम) से जुड़े तरीकों की व्याख्या करनी चाहिए @UiThread से जोड़ें और सिर्फ़ ऐप्लिकेशन के लाइफ़साइकल से जुड़े तरीकों की व्याख्या करें @MainThread.

अगर क्लास के सभी तरीकों में थ्रेड करने की ज़रूरी शर्तें एक जैसी हैं, तो एक ही थ्रेड जोड़ा जा सकता है क्लास में एनोटेशन का इस्तेमाल करके पुष्टि करें कि क्लास में सभी मेथड को एक ही टाइप के थ्रेड.

आम तौर पर, थ्रेड एनोटेशन का इस्तेमाल इस बात की पुष्टि करने के लिए किया जाता है कि किस मेथड या क्लास के साथ एनोटेट किया गया है @WorkerThread को सिर्फ़ सही बैकग्राउंड थ्रेड से कॉल किया जाता है.

वैल्यू कंस्ट्रेंट एनोटेशन

@IntRange का इस्तेमाल करें, @FloatRange, और @Size व्याख्याएं पास किए गए पैरामीटर की वैल्यू की पुष्टि करना. @IntRange और @FloatRange, दोनों सबसे ज़्यादा फ़ायदेमंद साबित होते हैं, जब इन्हें ऐसे पैरामीटर पर लागू किया जाता है जहां उपयोगकर्ताओं को शायद गलत रेंज दिखे.

@IntRange एनोटेशन से पुष्टि होती है कि पूर्णांक या लंबा पैरामीटर मान तय सीमा के अंदर है. नीचे दिए गए उदाहरण से पता चलता है कि alpha पैरामीटर में 0 से 255 तक का कोई पूर्णांक मान होना चाहिए:

Kotlin

fun setAlpha(@IntRange(from = 0, to = 255) alpha: Int) { ... }

Java

public void setAlpha(@IntRange(from=0,to=255) int alpha) { ... }

@FloatRange एनोटेशन से यह पता चलता है कि फ़्लोट पैरामीटर या डबल पैरामीटर मान, फ़्लोटिंग पॉइंट वैल्यू की तय की गई रेंज के अंदर हो. नीचे दिए गए उदाहरण से पता चलता है कि alpha पैरामीटर में 0.0 से 1.0 तक की कोई फ़्लोट वैल्यू होनी चाहिए:

Kotlin

fun setAlpha(@FloatRange(from = 0.0, to = 1.0) alpha: Float) {...}

Java

public void setAlpha(@FloatRange(from=0.0, to=1.0) float alpha) {...}

@Size एनोटेशन, कलेक्शन के साइज़ की जांच करता है या अरे या स्ट्रिंग की लंबाई. @Size एनोटेशन का इस्तेमाल, कारोबार की पुष्टि करने के लिए किया जा सकता है ये क्वालिटी सेट कर सकते हैं:

• कम से कम साइज़, जैसे कि @Size(min=2)
• ज़्यादा से ज़्यादा साइज़, जैसे कि @Size(max=2)
• सटीक साइज़, जैसे कि @Size(2)
• वह संख्या जिसका साइज़ उसका गुणांक होना चाहिए, जैसे कि @Size(multiple=2)

उदाहरण के लिए, @Size(min=1) यह जांचता है कि क्या कलेक्शन खाली नहीं है. साथ ही, @Size(3) यह पुष्टि करता है कि किसी अरे में सिर्फ़ तीन वैल्यू हैं.

नीचे दिए गए उदाहरण से पता चलता है कि location कलेक्शन में कम से कम एक एलिमेंट होना चाहिए:

Kotlin

fun getLocation(button: View, @Size(min=1) location: IntArray) {
    button.getLocationOnScreen(location)
}

Java

void getLocation(View button, @Size(min=1) int[] location) {
    button.getLocationOnScreen(location);
}

अनुमति के एनोटेशन

@RequiresPermission का इस्तेमाल करना एनोटेशन का इस्तेमाल करें. किसी एक अनुमति की जांच करने के लिए मान्य अनुमतियों की सूची में से, anyOf एट्रिब्यूट का इस्तेमाल करें. ऐसे सेट की जाँच करने के लिए अनुमतियां देने के लिए, allOf एट्रिब्यूट का इस्तेमाल करें. नीचे दिए गए उदाहरण में setWallpaper() तरीका बताता है कि तरीके के कॉलर के पास permission.SET_WALLPAPERS अनुमति:

Kotlin

@RequiresPermission(Manifest.permission.SET_WALLPAPER)
@Throws(IOException::class)
abstract fun setWallpaper(bitmap: Bitmap)

Java

@RequiresPermission(Manifest.permission.SET_WALLPAPER)
public abstract void setWallpaper(Bitmap bitmap) throws IOException;

नीचे दिए गए उदाहरण में, copyImageFile() मेथड का कॉलर होना ज़रूरी है बाहरी स्टोरेज को पढ़ने का ऐक्सेस और जगह की जानकारी का रीड ऐक्सेस, दोनों कॉपी की गई इमेज में दिया गया मेटाडेटा:

Kotlin

@RequiresPermission(allOf = [
    Manifest.permission.READ_EXTERNAL_STORAGE,
    Manifest.permission.ACCESS_MEDIA_LOCATION
])
fun copyImageFile(dest: String, source: String) {
    ...
}

Java

@RequiresPermission(allOf = {
    Manifest.permission.READ_EXTERNAL_STORAGE,
    Manifest.permission.ACCESS_MEDIA_LOCATION})
public static final void copyImageFile(String dest, String source) {
    //...
}

इंटेंट पर अनुमतियों के लिए, अनुमति की ज़रूरत को उस स्ट्रिंग फ़ील्ड पर रखें जो इंटेंट कार्रवाई का नाम:

Kotlin

@RequiresPermission(android.Manifest.permission.BLUETOOTH)
const val ACTION_REQUEST_DISCOVERABLE = "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE"

Java

@RequiresPermission(android.Manifest.permission.BLUETOOTH)
public static final String ACTION_REQUEST_DISCOVERABLE =
            "android.bluetooth.adapter.action.REQUEST_DISCOVERABLE";

कॉन्टेंट देने वाले उन लोगों या कंपनियों के लिए, जिन्हें पढ़ने और लिखने के लिए अलग-अलग अनुमतियों की ज़रूरत होती है ऐक्सेस करें, तो अनुमति की हर शर्त को @RequiresPermission.Read में शामिल करें या @RequiresPermission.Write एनोटेशन:

Kotlin

@RequiresPermission.Read(RequiresPermission(READ_HISTORY_BOOKMARKS))
@RequiresPermission.Write(RequiresPermission(WRITE_HISTORY_BOOKMARKS))
val BOOKMARKS_URI = Uri.parse("content://browser/bookmarks")

Java

@RequiresPermission.Read(@RequiresPermission(READ_HISTORY_BOOKMARKS))
@RequiresPermission.Write(@RequiresPermission(WRITE_HISTORY_BOOKMARKS))
public static final Uri BOOKMARKS_URI = Uri.parse("content://browser/bookmarks");

सीधे तौर पर नहीं मिलने वाली अनुमतियां

जब कोई अनुमति किसी तरीके के पैरामीटर को दी गई खास वैल्यू पर निर्भर करती है, तो इसका इस्तेमाल करें @RequiresPermission. उदाहरण के लिए, startActivity(Intent) यह तरीका, तरीके को पास किए गए इंटेंट पर सीधे पता न चलने वाली अनुमति का इस्तेमाल करता है:

Kotlin

abstract fun startActivity(@RequiresPermission intent: Intent, bundle: Bundle?)

Java

public abstract void startActivity(@RequiresPermission Intent intent, @Nullable Bundle)

जब सीधे तौर पर ऐक्सेस न की जा सकने वाली अनुमतियों का इस्तेमाल किया जाता है, तो बिल्ड टूल डेटा फ़्लो का विश्लेषण करके यह पता लगाता है कि तरीके में दिए गए आर्ग्युमेंट में कोई @RequiresPermission एनोटेशन है. इसके बाद पैरामीटर से कोई मौजूदा एनोटेशन को तरीके पर ही लागू करें. इस startActivity(Intent) उदाहरण के लिए, Intent क्लास में एनोटेशन के नतीजे के तौर पर चेतावनियां दिखती हैं startActivity(Intent) के अमान्य इस्तेमाल पर तब लागू होता है, जब इंटेंट के मुताबिक अनुमतियों को इस तरीके को पास किया जाता है, जैसा कि पहली इमेज में दिखाया गया है.

पहला डायग्राम. किसी इनडायरेक्ट विज़िट से जनरेट हुई चेतावनी startActivity(Intent) तरीके पर अनुमतियों के बारे में जानकारी.

बिल्ड टूल, startActivity(Intent) पर एनोटेशन से चेतावनी जनरेट करते हैं Intent क्लास में संबंधित इंटेंट कार्रवाई के नाम पर:

Kotlin

@RequiresPermission(Manifest.permission.CALL_PHONE)
const val ACTION_CALL = "android.intent.action.CALL"

Java

@RequiresPermission(Manifest.permission.CALL_PHONE)
public static final String ACTION_CALL = "android.intent.action.CALL";

अगर ज़रूरी हो, तो आप इन्हें @RequiresPermission से बदल सकते हैं व्याख्या करते समय @RequiresPermission.Read या @RequiresPermission.Write तरीके का पैरामीटर है. हालांकि, सीधे पता न चलने वाली अनुमतियों के लिए @RequiresPermission को यह करना चाहिए इसे पढ़ने या लिखने की अनुमतियों के एनोटेशन के साथ इस्तेमाल नहीं किया जाना चाहिए.

रिटर्न वैल्यू के एनोटेशन

@CheckResult एनोटेशन का इस्तेमाल करके, यह पुष्टि करना कि किसी तरीके के नतीजे या रिटर्न वैल्यू का इस्तेमाल किया गया है. हर बार टिप्पणी करने के बजाय @CheckResult के साथ बिना काम का तरीका, इसके नतीजों को साफ़ तौर पर बताने के लिए एनोटेशन जोड़ें ऐसे तरीके इस्तेमाल किए जा सकते हैं जिनसे भ्रम की स्थिति पैदा हो सकती है.

उदाहरण के लिए, नए Java डेवलपर अक्सर गलती से यह सोचते हैं कि <String>.trim(), ओरिजनल स्ट्रिंग से खाली सफ़ेद जगह हटा देता है. एनोटेट करना @CheckResult फ़्लैग वाली विधि <String>.trim() का इस्तेमाल करती है जहां कॉलर, तरीके की रिटर्न वैल्यू में कोई बदलाव नहीं करता है.

नीचे दिए गए उदाहरण में, checkPermissions() के बारे में बताया गया है यह पता लगाने का तरीका कि इस तरीके की रिटर्न वैल्यू संदर्भ दिया गया है. यह enforcePermission() का भी नाम रखता है के तौर पर दी गई है:

Kotlin

@CheckResult(suggest = "#enforcePermission(String,int,int,String)")
abstract fun checkPermission(permission: String, pid: Int, uid: Int): Int

Java

@CheckResult(suggest="#enforcePermission(String,int,int,String)")
public abstract int checkPermission(@NonNull String permission, int pid, int uid);

CallSuper एनोटेशन

@CallSuper एनोटेशन का इस्तेमाल करके, यह पुष्टि करने के लिए कि ओवरराइड करने का तरीका, मेथड के सुपर इंप्लीमेंटेशन को कॉल करता है.

नीचे दिए गए उदाहरण में, onCreate() मेथड के बारे में बताया गया है, ताकि यह पक्का किया जा सके कि ओवरराइड करने का कोई भी तरीका हो लागू करने के लिए कॉल super.onCreate():

Kotlin

@CallSuper
override fun onCreate(savedInstanceState: Bundle?) {
}

Java

@CallSuper
protected void onCreate(Bundle savedInstanceState) {
}

Typedef एनोटेशन

Typedef एनोटेशन की मदद से यह पता लगाया जाता है कि कोई खास पैरामीटर, रिटर्न वैल्यू, या फ़ील्ड, कॉन्सटेंट के खास सेट का रेफ़रंस देता है. इनकी मदद से, कोड पूरा होने की सुविधा भी अपने-आप चालू हो जाती है स्वीकृत स्थिरांक उपलब्ध कराएं.

@IntDef का इस्तेमाल करें और @StringDef एनोटेशन कई तरह के कोड रेफ़रंस होते हैं.

Typeif एनोटेशन में, गिनती वाले नए टाइप का एलान करने के लिए, @interface का इस्तेमाल किया जाता है. @IntDef और @StringDef एनोटेशन के साथ @Retention के साथ, नई व्याख्या के बारे में बताएं. साथ ही, टाइप की सूची में शामिल है. @Retention(RetentionPolicy.SOURCE) एनोटेशन से कंपाइलर को जानकारी मिलती है .class फ़ाइल में गिने गए एनोटेशन डेटा को सेव न करें.

इस उदाहरण में, एनोटेशन बनाने का तरीका बताया गया है. इससे यह पता चलेगा कि कोई वैल्यू पास हुई है या नहीं के तौर पर:

Kotlin

import androidx.annotation.IntDef
//...
// Define the list of accepted constants and declare the NavigationMode annotation.
@Retention(AnnotationRetention.SOURCE)
@IntDef(NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS)
annotation class NavigationMode

// Declare the constants.
const val NAVIGATION_MODE_STANDARD = 0
const val NAVIGATION_MODE_LIST = 1
const val NAVIGATION_MODE_TABS = 2

abstract class ActionBar {

    // Decorate the target methods with the annotation.
    // Attach the annotation.
    @get:NavigationMode
    @setparam:NavigationMode
    abstract var navigationMode: Int

}

Java

import androidx.annotation.IntDef;
//...
public abstract class ActionBar {
    //...
    // Define the list of accepted constants and declare the NavigationMode annotation.
    @Retention(RetentionPolicy.SOURCE)
    @IntDef({NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST, NAVIGATION_MODE_TABS})
    public @interface NavigationMode {}

    // Declare the constants.
    public static final int NAVIGATION_MODE_STANDARD = 0;
    public static final int NAVIGATION_MODE_LIST = 1;
    public static final int NAVIGATION_MODE_TABS = 2;

    // Decorate the target methods with the annotation.
    @NavigationMode
    public abstract int getNavigationMode();

    // Attach the annotation.
    public abstract void setNavigationMode(@NavigationMode int mode);
}

इस कोड को बनाने पर, अगर mode पैरामीटर नहीं होता है, तो एक चेतावनी जनरेट होती है किसी तय कॉन्सटेंट (NAVIGATION_MODE_STANDARD, NAVIGATION_MODE_LIST या NAVIGATION_MODE_TABS).

@IntDef और @IntRange को मिलाएं, ताकि यह पता चल सके कि पूर्णांक, कॉन्सटेंट का दिया हुआ सेट या रेंज में मौजूद कोई वैल्यू हो सकती है.

फ़्लैग के साथ कॉन्सटेंट को जोड़ना चालू करें

अगर उपयोगकर्ता, स्वीकार किए गए कॉन्सटेंट को फ़्लैग (जैसे कि |, &, ^ वगैरह), तो आपके पास flag एट्रिब्यूट का इस्तेमाल करके, यह पता लगाया जाता है कि कोई पैरामीटर या रिटर्न वैल्यू मान्य पैटर्न का रेफ़रंस देती है या नहीं.

इस उदाहरण में, मान्य लिस्ट के साथ DisplayOptions एनोटेशन बनाया गया है DISPLAY_ कॉन्सटेंट:

Kotlin

import androidx.annotation.IntDef
...

@IntDef(flag = true, value = [
    DISPLAY_USE_LOGO,
    DISPLAY_SHOW_HOME,
    DISPLAY_HOME_AS_UP,
    DISPLAY_SHOW_TITLE,
    DISPLAY_SHOW_CUSTOM
])
@Retention(AnnotationRetention.SOURCE)
annotation class DisplayOptions
...

Java

import androidx.annotation.IntDef;
...

@IntDef(flag=true, value={
        DISPLAY_USE_LOGO,
        DISPLAY_SHOW_HOME,
        DISPLAY_HOME_AS_UP,
        DISPLAY_SHOW_TITLE,
        DISPLAY_SHOW_CUSTOM
})
@Retention(RetentionPolicy.SOURCE)
public @interface DisplayOptions {}

...

जब आप एनोटेशन फ़्लैग के साथ कोड बनाते हैं, तो एक चेतावनी जनरेट होती है. या रिटर्न वैल्यू किसी मान्य पैटर्न का रेफ़रंस नहीं देती है.

एनोटेशन को सेव रखें

@Keep एनोटेशन यह पक्का करता है कि जब कोड बिल्ड के समय कम से कम होता है. आम तौर पर, यह एनोटेशन को उन तरीकों और क्लास में जोड़ा जाता है जिन्हें रिफ़्लेक्शन के ज़रिए ऐक्सेस किया जाता है, ताकि कंपाइलर को कोड को इस्तेमाल नहीं हुआ है.

चेतावनी: वे क्लास और तरीके जिनके बारे में आपने जानकारी दी है @Keep का उपयोग करने से वे हमेशा आपके ऐप्लिकेशन के APK में दिखाई देते हैं, भले ही आपको अपने ऐप्लिकेशन के तर्क के हिसाब से, इन क्लास और तरीकों का रेफ़रंस दें.

अपने ऐप्लिकेशन का साइज़ छोटा रखने के लिए, यह देखें कि क्या आपके ऐप्लिकेशन में हर @Keep एनोटेशन. अगर आप रिफ़्लेक्शन की मदद से व्याख्या की गई क्लास या मेथड को ऐक्सेस करने के लिए, -if एट्रिब्यूट की वैल्यू के तौर पर, ProGuard के नियमों में क्लास की जानकारी दी गई है जिससे मनोदशा का पता चलता है.

अपने कोड को छोटा करने के तरीके के बारे में ज़्यादा जानने और यह तय करने के लिए कि किस कोड को नहीं हटाया जाना है, अपने ऐप्लिकेशन को छोटा करना, अस्पष्ट बनाना, और उसे ऑप्टिमाइज़ करना लेख पढ़ें.

कोड दिखने से जुड़े एनोटेशन

कोड के खास हिस्से किसको दिखे, यह बताने के लिए इन एनोटेशन का इस्तेमाल करें, जैसे कि तरीके, क्लास, फ़ील्ड या पैकेज.

जांच के लिए कोड को दिखाएं

कॉन्टेंट बनाने @VisibleForTesting यह बताता है कि टिप्पणी करने का तरीका, सामान्य तरीके से ज़्यादा दिख रहा है. तरीका टेस्ट करने लायक है. इस जानकारी में एक वैकल्पिक otherwise तर्क है, जो आपको अगर आपके चुने गए तरीके को दिखाने की ज़रूरत नहीं है, तो यह बताएं कि इस तरीके के दिखने की स्थिति क्या होगी इस टूल का इस्तेमाल किया जा सकता है. चुनी गई जानकारी को लागू करने के लिए, लिंट otherwise आर्ग्युमेंट का इस्तेमाल करता है.

यहां दिए गए उदाहरण में, आम तौर पर myMethod(), private होता है, लेकिन यह टेस्ट के लिए package-private. VisibleForTesting.PRIVATE के साथ डेज़िगनेशन, अगर इस तरीके को private ऐक्सेस के ज़रिए दिया गया संदर्भ इस्तेमाल करता हो. जैसे, किसी दूसरे कंपाइलेशन यूनिट से.

Kotlin

@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
fun myMethod() {
    ...
}

Java

@VisibleForTesting(otherwise = VisibleForTesting.PRIVATE)
void myMethod() { ... }

@VisibleForTesting(otherwise = VisibleForTesting.NONE) की जानकारी भी दी जा सकती है जो बताता है कि तरीका सिर्फ़ टेस्टिंग के लिए मौजूद है. यह फ़ॉर्म, @RestrictTo(TESTS). वे दोनों एक ही लिंट जांच करते हैं.

एपीआई पर पाबंदी लगाना

@RestrictTo एनोटेशन से पता चलता है कि एनोटेशन वाले एपीआई (पैकेज, क्लास या मेथड) का ऐक्सेस सीमित है, इस तरह से:

सब-क्लास

पाबंदी लगाने के लिए, जानकारी देने वाले फ़ॉर्म @RestrictTo(RestrictTo.Scope.SUBCLASSES) का इस्तेमाल करें सिर्फ़ सब-क्लास के लिए एपीआई का ऐक्सेस.

इस एपीआई को सिर्फ़ वे क्लास ऐक्सेस कर सकती हैं जो एनोटेट की गई क्लास को बढ़ाती हैं. Java protected मॉडिफ़ायर में बहुत ज़्यादा पाबंदी नहीं है, क्योंकि यह ऐक्सेस करने की अनुमति देता है एक ही पैकेज में असंबंधित क्लास की मदद से. इसके अलावा, कुछ मामलों में आपको विधि public, ताकि आप भविष्य में कभी भी protected और ओवरराइड किया गया public तरीका है, लेकिन आप कोई वैल्यू देना चाहते हैं यह संकेत देता है कि क्लास या सब-क्लास में इस्तेमाल किए जाने के लिए है.

पुस्तकालय

इसके लिए, एनोटेशन फ़ॉर्म @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP_PREFIX) का इस्तेमाल करें इसकी मदद से, सिर्फ़ अपनी लाइब्रेरी में एपीआई ऐक्सेस को प्रतिबंधित किया जा सकता है.

सिर्फ़ आपकी लाइब्रेरी का कोड, एनोटेशन वाले एपीआई को ऐक्सेस कर सकता है. इससे न सिर्फ़ आपके कोड को व्यवस्थित किया जा सकता है, किसी भी टूल का इस्तेमाल करके, कोड को संबंधित लाइब्रेरी के ग्रुप में शामिल करता है. यह विकल्प Jetpack में पहले से ही मौजूद है ऐसी लाइब्रेरी जिनमें बहुत सारे कोड लागू होते हैं, जो बाहरी इस्तेमाल के लिए नहीं होते हैं, लेकिन इसे अलग-अलग पूरक Jetpack लाइब्रेरी में शेयर करने के लिए, public होना चाहिए.

टेस्ट करना

अन्य जानकारी को फैलने से रोकने के लिए, जानकारी देने वाले फ़ॉर्म @RestrictTo(RestrictTo.Scope.TESTS) का इस्तेमाल करें डेवलपर को आपके टेस्टिंग एपीआई ऐक्सेस करने से रोकना.

एनोटेशन वाले एपीआई को सिर्फ़ टेस्टिंग कोड ऐक्सेस कर सकता है. इससे दूसरे डेवलपर को को डेवलपमेंट के लिए उस एपीआई का इस्तेमाल करना ज़रूरी है जिसे सिर्फ़ टेस्टिंग के लिए इस्तेमाल किया जाना है.