एपीआई प्रलेखन फ़ंक्शन मापदंडों की व्याख्या कैसे करें?

103

क्या एपीआई दस्तावेज़ों में फ़ंक्शन इंटरफेस के सिंटैक्स की व्याख्या करने के लिए एक मानक है और यदि हाँ, तो इसे कैसे परिभाषित किया गया है?

इस बात पर एक उदाहरण है कि "fillColor" फ़ंक्शन के लिए फ़ोटोशॉप के लिए जावास्क्रिप्ट स्क्रिप्टिंग गाइड किसी आइटम का रंग कैसे बदलना है:

fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])

कोष्ठक का क्या अर्थ है और कोष्ठक में अल्पविराम क्यों हैं? यह निम्नलिखित उदाहरण कॉल से कैसे संबंधित है?

myPath.fillPath(myNewColor)

myPath.fillPath(mynewColor, {
    mode: RGB,
    opacity: .5
})

api documentation

— dbonneville
स्रोत

4

क्या एपीआई संदर्भ दस्तावेज का कोई परिचय है जो उनके वाक्यात्मक सम्मेलनों का वर्णन करता है?

— ग्रेग हेविल जिल

35

उस व्यक्ति के लिए जिसने मतदान करना बंद कर दिया है: मेरा मानना है कि इस प्रश्न में योग्यता है, और अगर मैं कर सकता हूं तो "वोट बंद न करने" के लिए। यह एक ऐसा सवाल नहीं है जिसे मैंने पहले देखा है (या सुना है), यह एक वैध प्रोग्रामिंग-संबंधित समस्या को संबोधित करता है, और जब मैं लोगों को प्रोग्रामिंग से संबंधित चीजें सिखाता हूं, तो मुझे व्यक्तिगत रूप से उत्तर उपयोगी मिलेगा।

— डेविड वोलेवर

4

डेरेक: मुझे लगता है कि आपने मूल पोस्ट में बोल्ड वाक्यों में से एक को याद किया। यदि आप "api दस्तावेज़ीकरण को कैसे पढ़ें" को गूगल करते हैं, तो पहले 10 परिणामों में जानकारी "अमूर्त", "अपूर्ण", "भ्रमित", आदि जैसी बातें कहती है, इस प्रकार मेरे प्रश्न के बिंदु को पुष्ट करती है।

— dbonneville

2

ग्रेग: फ़ोटोशॉप / एडोब उत्पादों के लिए कोई परिचय नहीं है। वे सभी प्रति उत्पाद 2 पीडीएफ में एक ही प्रारूप का पालन करते हैं। दूसरे एपीआई जो मैं करने की सोच रहा हूं, वही करें। एक निहित ज्ञान है कि मैं कई मामलों में नहीं है और निश्चित रूप से करना चाहते हैं।

— dbonneville

1

एक उपयोगी संसाधन एक्स्टेंडस्क्रिप्ट आईडीई (हिट एफ 1) में निर्मित वस्तु दर्शक है। किसी ऑब्जेक्ट पर क्लिक करने से आपको पता चलेगा कि उसके पास क्या गुण और विधियाँ हैं। इसके अलावा अगर यह अन्य वस्तुओं का उपयोग मापदंडों के रूप में करता है (आमतौर पर) उनसे लिंक करता है तो आप देख सकते हैं कि उनके पास क्या गुण हैं। यह सही नहीं है, लेकिन यह मदद करता है।

— pdizz

92

तो एपीआई दस्तावेज़ीकरण को इस तरह से क्यों लिखा जाता है जैसे कि बारहमासी नवाबों / हैकर्स / DIYers को भ्रमित करना?

यह वास्तव में इस तरह से लिखे जाने का मतलब नहीं है। मैं मानता हूँ कि एपीआई दस्तावेज़ों में उपयोग में आसानी नहीं होगी। हालाँकि, पुराने manस्टाइल के सिंटैक्स कन्वेंशन से लेकर आधुनिक एपीआई / नेमस्पेस कन्वेंशन तक बहुत कुछ क्रॉस किया जाता है ।

आमतौर पर, एपीआई के साथ काम करने वाले व्यक्ति का प्रकार विकास में कुछ पृष्ठभूमि या कम से कम एक 'पावर उपयोगकर्ता' होगा। इस प्रकार के उपयोगकर्ताओं को इस तरह के वाक्यविन्यास सम्मेलनों के लिए उपयोग किया जाता है और यह एपीआई दस्तावेज़ के लिए नए लोगों को बनाने की कोशिश करने की तुलना में अधिक समझ में आता है।

क्या कहीं कोई रहस्यमय दस्तावेज है जो लोगों को एपीआई प्रलेखन को पढ़ने के तरीके बताता है?

वास्तव में कोई मानक नहीं है, या RFC, कहीं भी चारों ओर बिछाने supersekretsyntaxdoc, हालांकि UNIX मैन पेज सिनॉप्सिस प्रारूप के लिए एक ~ 30 वर्ष पुरानी फ़ाइल है जो व्यापक उपयोग है।

इसके कुछ उदाहरण (और आपके प्रश्न का उत्तर) होंगे:

रेखांकित शब्दों को शाब्दिक माना जाता है, और जैसे ही वे दिखाई देते हैं, टाइप किया जाता है।

स्क्वायर ब्रैकेट ([]) एक तर्क के आसपास इंगित करता है कि तर्क वैकल्पिक है।

दीर्घवृत्त ... का उपयोग यह दिखाने के लिए किया जाता है कि पिछले तर्क-प्रोटोटाइप को दोहराया जा सकता है।

माइनस साइन के साथ शुरू होने वाला एक तर्क - अक्सर कुछ प्रकार के फ्लैग तर्क का अर्थ लिया जाता है, भले ही यह एक ऐसी स्थिति में दिखाई देता है जहां एक फ़ाइल नाम दिखाई दे सकता है।

लगभग सभी प्रोग्रामिंग संबंधित प्रलेखन इस प्रकार के वाक्यविन्यास सम्मेलन का उपयोग करता है, पायथन से , मैन पेज , जावास्क्रिप्ट लिबास ( हाईचर ), आदि।

एडोब एपीआई से अपने उदाहरण को तोड़कर

fillPath
([fillColor]
[, mode]
[, opacity]
[, preserveTransparency] [, feather]
[, wholePath] [, antiAlias])

हम देखते हैं कि fillPath()(एक फ़ंक्शन) वैकल्पिक तर्क लेता है fillColor, mode, opacity, preserveTransparency, feathe, wholePathया antiAlias। कॉलिंग fillPath(), आप उन मापदंडों में से किसी को, सभी को, कहीं से भी पारित कर सकते हैं। वैकल्पिक के भीतर अल्पविराम का []अर्थ है कि यदि यह पैरामीटर दूसरों के अतिरिक्त उपयोग किया जाता है, तो आपको इसे अलग करने के लिए अल्पविराम की आवश्यकता है। (सामान्य ज्ञान कभी-कभी, निश्चित रूप से, लेकिन कभी-कभी कुछ भाषाओं जैसे VB, को स्पष्ट रूप से उन अल्पविरामों की आवश्यकता होती है जो ठीक से परिसीमन करने के लिए हैं। पैरामीटर गायब है!)। चूँकि आपने प्रलेखन से लिंक नहीं किया था (और मैं इसे Adobe के स्क्रिप्टिंग पेज पर नहीं खोज सकता ) वास्तव में यह जानने का कोई तरीका नहीं है कि Adobe API किस प्रारूप की अपेक्षा कर रहा है। हालाँकि, भीतर उपयोग किए जाने वाले सम्मेलनों की व्याख्या करने वाले अधिकांश प्रलेखन के शीर्ष पर एक स्पष्टीकरण होना चाहिए ।

इसलिए, इस फ़ंक्शन का उपयोग कई तरीकों से किया जा सकता है:

fillPath() //Nothing passed
fillPath(#000000,RGB) // Black, in RGB mode
fillPath(#000000,RGB,50) // Black, in RGB mode, half opacity

//Now it gets tricky, this might ALSO be acceptable:
fillPath(#000000,50) // Black, no mode, half opacity

//OR
fillPath(#000000,,50) // Black, no mode, half opacity

फिर, आमतौर पर एपीआई / प्रोग्रामिंग से संबंधित सभी दस्तावेजों में कुछ मानक हैं। हालांकि प्रत्येक डॉक्टर में, सूक्ष्म अंतर हो सकते हैं। एक बिजली उपयोगकर्ता, या डेवलपर के रूप में, आपको उन दस्तावेज़ों / रूपरेखाओं / पुस्तकालयों को पढ़ने और समझने में सक्षम होने की उम्मीद है जिनका आप उपयोग करने का प्रयास कर रहे हैं।

— PenguinCoder
स्रोत

5

UNIX मैन पेज सिनोप्सिस प्रारूप लिंक मृत है - किसी के पास प्रतिस्थापन लिंक है? @PenguinCoder अपडेट: [ unix.stackexchange.com/questions/17833/… (Unix Stack Exchange) पर आधारित है, यह शिथिल रूप से [ en.wikipedia.org/wiki/Edended_Backus%E2%80N93_Form (EBNF)

— steviejay

मैन पेज सिनोप्सिस फॉर्मेट की एक संग्रहीत प्रति है

— कोडमैनएक्स

5

गतिशील रूप से टाइप की गई भाषाओं के लिए एपीआई डॉक्स बहुत सार्थक नहीं हो सकते हैं यदि ध्यान से नहीं लिखा गया है, तो इसके बारे में बहुत बुरा नहीं लगता है, यहां तक कि सबसे अनुभवी डेवलपर को उन्हें समझने की कोशिश करने में कठिन समय हो सकता है।

कोष्ठक और इस तरह के बारे में, आमतौर पर एक कोड कन्वेंशन अनुभाग है जो शाब्दिक उदाहरणों के बाहर सटीक उपयोग की व्याख्या करना चाहिए; हालांकि EBNF , Regex और Railroad Diagrams लगभग सर्वव्यापी हैं, इसलिए आपको अधिकांश नोटेशन को समझने के लिए उनसे परिचित होना चाहिए।

— fortran
स्रोत

3

कोष्ठक का अर्थ है कि संपत्ति वैकल्पिक है। हालांकि ध्यान रखें कि यदि आप nTh रैंक पर कुछ संपत्ति सेट करना चाहते हैं, तो आपको या तो अग्रणी के लिए संपत्तियों को घोषित करना होगा या उन्हें अपरिभाषित घोषित करना होगा:

fillPath() //good
fillPath ( someFillColor ) //good
fillPath ( someFillColor, mode ) //good
fillPath ( undefined, mode ) //good
fillPath ( mode ) //bad
fillPath ( undefined ) //really bad

— लोइक ऐगॉन
स्रोत

2

fillPath (mode)ठीक हो सकता है। यदि एक वैकल्पिक तर्क एक गैर-वैकल्पिक से पहले आता है, तो इसका मतलब यह है कि वैकल्पिक तर्क देने के लिए फ़ंक्शन स्मार्ट है या नहीं (उदाहरण के लिए इसके प्रकार को

— देखकर

1

एमएमएम अच्छी तरह से संभव है, लेकिन मैं इस बात पर भरोसा करना पसंद करता हूं कि स्क्रिप्ट मेरे लिए क्या कर सकती है: डी

— लॉजिक एगॉन

1

कुछ समय पहले मेरा भी यही सवाल था और किसी ने मुझे विस्तारित बैकस-नौर फॉर्म की ओर इशारा किया ।

यह समझ में आता है क्योंकि प्रोग्रामिंग का उपयोग संभावित असीम परिणामों को बनाने के लिए किया जा सकता है। प्रलेखन हर संभव मामले के लिए एक उदाहरण प्रदर्शित नहीं कर सकता है। सामान्य उपयोग का एक अच्छा उदाहरण मैं सहायक हूं लेकिन एक बार जब आप अंतर्निहित सिंटैक्स पढ़ सकते हैं तो आप अपना कोड बना सकते हैं।

— StevenKW
स्रोत