Qt 5.11 - Categories of Documentation

प्रलेखन की श्रेणियाँ




qt

प्रलेखन की श्रेणियाँ

कई प्रकार के पूर्वनिर्धारित दस्तावेज श्रेणियां या प्रकार हैं :

  • कैसे tos
  • ट्यूटोरियल
  • अवलोकन
  • लेख
  • सामान्य प्रश्न (अक्सर पूछे जाने वाले प्रश्न)
  • सी ++ एपीआई प्रलेखन
  • QML प्रकार दस्तावेज़
  • कोड उदाहरण

QDoc में टाइप के आधार पर पेज को फॉर्मेट करने की क्षमता है। इसके अलावा, स्टाइलशीट प्रत्येक श्रेणी के प्रदर्शन पर अतिरिक्त नियंत्रण प्रदान कर सकते हैं।

एपीआई प्रलेखन

एपीआई प्रलेखन के निर्माण में QDoc एक्सेल ने QDoc टिप्पणियों में स्रोत कोड और प्रलेखन का एक सेट दिया। विशेष रूप से, QDoc Qt की वास्तुकला से अवगत है और Qt C ++ वर्ग, फ़ंक्शन, या संपत्ति प्रलेखन के अस्तित्व को मान्य कर सकता है। QDoc चेतावनियों और त्रुटियों को देता है यदि वह किसी कोड इकाई के साथ प्रलेखन को संबद्ध नहीं कर सकता है या यदि कोड इकाई के पास दस्तावेज़ीकरण नहीं है।

सामान्य तौर पर, प्रत्येक Qt कोड इकाई जैसे कि गुण, वर्ग, विधियाँ, संकेत, और गणना के अनुरूप विषय कमांड होती है । QDoc C ++ नामकरण नियमों का उपयोग करके दस्तावेज़ को स्रोत से संबद्ध करेगा।

QDoc वर्ग संरचनाओं का एक पेड़ बनाने के लिए हेडर फ़ाइलों (आमतौर पर .h फ़ाइलों) को पार्स करेगा। तब QDoc स्रोत फ़ाइलों और दस्तावेज़ फ़ाइलों को वर्ग संरचना में दस्तावेज़ संलग्न करने के लिए पार्स करेगा। बाद में, QDoc क्लास के लिए एक पेज बनाएगा।

नोट: QDoc खुद को वर्ग के बारे में सूचित करने के लिए हेडर फ़ाइलों का उपयोग करता है और हेडर फ़ाइलों में QDoc टिप्पणियों को ठीक से संसाधित नहीं करेगा।

भाषा शैलियाँ

गुणवत्ता एपीआई प्रलेखन का उत्पादन करने के लिए, क्यूटी एपीआई संदर्भ एक विशेष भाषा दिशानिर्देशों का पालन करते हैं। जबकि इस पृष्ठ की सामग्री यह दर्शाती है कि एपीआई प्रलेखन कैसे बनाया जाता है, शैली दिशानिर्देश यह प्रदर्शित करते हैं कि संदर्भ सामग्री भाषा के लगातार उपयोग का पालन कैसे करती है।

प्रलेखित QML प्रकार

QML की दुनिया में, अतिरिक्त QML हैं जिन्हें हमें क्यूएमएल संकेतों, संलग्न गुणों और क्यूएमएल विधियों जैसे दस्तावेज़ों की आवश्यकता है। आंतरिक रूप से, वे क्यूटी प्रौद्योगिकियों का उपयोग करते हैं, हालांकि, क्यूएमएल एपीआई प्रलेखन को क्यूटी सी ++ एपीआई प्रलेखन से अलग लेआउट और नामकरण सम्मेलनों की आवश्यकता होती है।

QML संबंधित QDoc कमांड की एक सूची:

नोट: याद रखें कि क्यूएमएल पार्सिंग को *.qml फ़ाइलप्राइप को fileextension चर में शामिल करके fileextension करें।

QML प्रकार का दस्तावेज़ करने के लिए, QDoc टिप्पणी बनाकर शुरू करें जो अपने विषय कमांड के रूप में \qmltype कमांड का उपयोग करती है।

QML पार्सर

यदि आपका QML प्रकार एक qml फ़ाइल में परिभाषित किया गया है, तो इसे वहां दस्तावेज़ित करें यदि आपका QML प्रकार C ++ वर्ग द्वारा दर्शाया गया है, तो उस C ++ वर्ग के लिए cpp फ़ाइल में दस्तावेज़ करें और C ++ वर्ग के नाम को निर्दिष्ट करने के लिए एक \instantiates कमांड शामिल करें। क्यूपी प्रकार में क्यूएमएल प्रकार का दस्तावेज़ न करें यदि क्यूएमएल प्रकार को क्यूएमएल फ़ाइल में परिभाषित किया गया है।

क्यूएमएल फ़ाइल में क्यूएमएल प्रकार का दस्तावेजीकरण करते समय, प्रत्येक क्यूडॉक टिप्पणी को उस इकाई के ऊपर सीधे रखें जिस पर टिप्पणी लागू होती है। उदाहरण के लिए, QDoc टिप्पणी को सीधे qml फ़ाइल में बाहरी QML प्रकार के ऊपर \ qmltype कमांड (विषय टिप्पणी) युक्त रखें । प्रॉपर्टी डिक्लेरेशन के ऊपर सीधे क्यूएमएल संपत्ति के दस्तावेज के लिए टिप्पणी रखें, और क्यूएमएल सिग्नल हैंडलर्स और क्यूएमएल विधियों के लिए। ध्यान दें कि क्यूएमएल फ़ाइल में क्यूएमएल गुण का दस्तावेज़ीकरण करते समय, आप सामान्य रूप से एक विषय कमांड के रूप में \ qmlproperty कमांड को शामिल नहीं करते हैं (जो आपको सीपीएम फ़ाइलों में क्यूएमएल प्रकार का दस्तावेजीकरण करते समय करना चाहिए), क्योंकि क्यूएमएल पार्सर स्वचालित रूप से अपने QDoc टिप्पणी के साथ संबद्ध करता है। अगले QML घोषणा यह पार्स करता है। QML सिग्नल हैंडलर और QML विधि टिप्पणियों के लिए भी यही सत्य है। लेकिन कभी-कभी टिप्पणी में एक या अधिक \ qmlproperty आदेशों को शामिल करना उपयोगी होता है, उदाहरण के लिए जब संपत्ति प्रकार एक और QML प्रकार है और आप चाहते हैं कि उपयोगकर्ता केवल कुछ अन्य QML प्रकारों के भीतर कुछ गुणों का उपयोग करें, लेकिन उन सभी को नहीं। लेकिन जब किसी संपत्ति का उपनाम होता है, तो दस्तावेजीकरण के लिए QDoc टिप्पणी को सीधे उपनाम की घोषणा से ऊपर रखें। इन मामलों में, QDoc टिप्पणी में एक \ qmlproperty कमांड होना चाहिए , क्योंकि यही एकमात्र तरीका है QDoc अलियास की गई संपत्ति के प्रकार को जान सकता है।

अपने संबंधित C ++ वर्ग (यदि यह एक है) की cpp फ़ाइल में QML प्रकार का दस्तावेजीकरण करते हैं, तो आप सामान्यतया प्रत्येक QDoc टिप्पणी को सीधे उस इकाई से ऊपर रख देते हैं, जिसे वह दस्तावेज कहता है। हालाँकि, QDoc इन फ़ाइलों को पार्स करने के लिए QML पार्सर का उपयोग नहीं करता है (C ++ पार्सर का उपयोग किया जाता है), इसलिए ये QML QDoc टिप्पणियाँ cpp फ़ाइल में कहीं भी दिखाई दे सकती हैं। ध्यान दें कि cpp फ़ाइलों में QML QDoc टिप्पणियों को QML विषय कमांड का उपयोग करना चाहिए । यानी, QML प्रकार के लिए \qmlproperty कमांड में \qmlproperty कमांड दिखाई देनी चाहिए , और प्रत्येक QML प्रॉपर्टी QDoc टिप्पणी में a \qmlproperty कमांड दिखाई देनी चाहिए

QML मॉड्यूल

क्यूएमएल प्रकार एक मॉड्यूल के अंतर्गत आता है। मॉड्यूल में प्लेटफ़ॉर्म के लिए सभी संबंधित प्रकार शामिल हो सकते हैं या QML का एक निश्चित संस्करण हो सकता है। उदाहरण के लिए, क्यूटी क्विक 2 क्यूएमएल प्रकार क्यूटी क्विक 2 मॉड्यूल के हैं, जबकि क्यूटी 4 में पेश किए गए पुराने प्रकारों के लिए क्यूटी क्विक 1 मॉड्यूल भी है।

क्यूएमएल मॉड्यूल क्यूएमएल प्रकारों को समूहीकृत करने की अनुमति देते हैं। क्यूएमएल मॉड्यूल के प्रकार से संबंधित करने के लिए \qmltype विषय कमांड में एक \inqmlmodule संदर्भ कमांड होना चाहिए। इसी तरह, मॉड्यूल के लिए अवलोकन पृष्ठ बनाने के लिए एक अलग .qdoc फ़ाइल में एक \qmlmodule विषय कमांड मौजूद होना चाहिए। अवलोकन पृष्ठ QML प्रकार के QML मॉड्यूल को सूचीबद्ध करेगा।

क्यूएमएल प्रकारों के लिंक में इसलिए मॉड्यूल नाम भी होना चाहिए। उदाहरण के लिए, यदि एक प्रकार जिसे TabWidget कहा जाता है, तो TabWidget मॉड्यूल में है, इसे UIComponents::TabWidget रूप में जोड़ा जाना चाहिए।

यूआईकॉम्प्टर के उदाहरण QML प्रकार और QML मॉड्यूल के दस्तावेज़ के लिए QDoc कमांड के उचित उपयोग को प्रदर्शित करते हैं।

केवल-पढ़ने के लिए और आंतरिक QML गुण

QDoc QML गुणों का पता लगाता है जिन्हें आसानी से चिह्नित किया जाता है। ध्यान दें कि संपत्ति को एक मूल्य के साथ आरंभ किया जाना चाहिए।

readonly property int sampleReadOnlyProperty: 0

उदाहरण के लिए, उदाहरण TabWidget प्रकार में एक काल्पनिक रीड-ओनली प्रॉपर्टी का sampleReadOnlyProperty । इसकी घोषणा में आसानी से पहचानकर्ता है और इसका प्रारंभिक मूल्य है।

गुण और संकेत जो सार्वजनिक इंटरफ़ेस के लिए नहीं हैं, उन्हें \internal कमांड के साथ चिह्नित किया जा सकता है। QDoc जनरेट किए गए आउटपुट में प्रलेखन प्रकाशित नहीं करेगा।

लेख और ओवरव्यू

लेख और साक्षात्कार एक विषय या अवधारणा पर सारांश विवरण प्रदान करने के लिए सबसे अच्छा लेखन की एक शैली है। यह एक तकनीक को पेश कर सकता है या चर्चा कर सकता है कि एक अवधारणा कैसे लागू की जा सकती है, लेकिन बहुत अधिक विस्तार से सटीक चरणों पर चर्चा किए बिना। हालाँकि, इस प्रकार की सामग्री पाठकों को निर्देशात्मक और संदर्भ सामग्री खोजने के लिए प्रवेश बिंदु प्रदान कर सकती है, जो कि ट्यूटोरियल, उदाहरण और वर्ग प्रलेखन जैसे कार्य करते हैं। अवलोकन का एक उदाहरण उत्पाद पृष्ठ हो सकता है, जैसे कि क्यूटी क्विक, व्यक्तिगत मॉड्यूल, डिजाइन सिद्धांत या उपकरण के शीर्ष स्तर की चर्चा।

यह दर्शाने के लिए कि एक दस्तावेज़ एक लेख है, आप लेख खोजशब्द को \ पृष्ठ कमांड में जोड़ते हैं:

/*!
    \page overview-qt-technology.html overview
    \title Overview of a Qt Technology

    \brief provides a technology never seen before.

*/

लेखन विषय कमांड अनुभाग में उपलब्ध \ पृष्ठ कमांड तर्कों की एक सूची है।

ट्यूटोरियल, हाउ-टू, एफएक्यू

ट्यूटोरियल, हाउ-टू और एफएक्यू सभी निर्देशात्मक सामग्री हैं, इसमें वे पाठक को निर्देश देते हैं या निर्धारित करते हैं। ट्यूटोरियल एक अवधारणा या प्रौद्योगिकी के लिए एक प्रगतिशील सीखने के मार्ग के साथ पाठक को मार्गदर्शन करने के लिए डिज़ाइन की गई सामग्री है। हाउ-टू और एफएक्यू ( अक्सर पूछे जाने वाले प्रश्न ) आमतौर पर पूछे जाने वाले विषयों के उत्तर के रूप में सामग्री पेश करके मार्गदर्शन प्रदान करते हैं। हाउ-टू और एफएक्यू को आसान संदर्भ के लिए डिज़ाइन किया गया है और जरूरी नहीं कि इसे रैखिक प्रगति में प्रस्तुत किया जाए।

इन प्रकारों को बनाने के लिए, \page कमांड को एक type तर्क देकर पृष्ठों को चिह्नित करें। type तर्क दूसरा तर्क है, जिसमें फ़ाइल नाम प्रथम है।

/*!
    \page altruism-faq.html faq
    \title Altruism Frequently Asked Questions

    \brief All the questions about altruism, answered.

    ...
*/

लेखन विषय कमांड अनुभाग में उपलब्ध \ पृष्ठ कमांड तर्कों की एक सूची है।

कोड उदाहरण

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

एक उदाहरण के साथ एक ट्यूटोरियल हो सकता है। ट्यूटोरियल कोड का निर्देश देता है और उसका वर्णन करता है, जबकि कोड उदाहरण वह कोड सामग्री है जो उपयोगकर्ता अध्ययन कर सकते हैं। कोड उदाहरण के साथ पाठ हो सकता है जो ट्यूटोरियल में नहीं है।

QDoc एक पेज बनाएगा, जिसमें उदाहरण कोड के साथ एक उदाहरण होगा जिसमें \example कमांड का उपयोग किया जाएगा।

/*!
    \title UI Components: Tab Widget Example
    \example declarative/ui-components/tabwidget

    This example shows how to create a tab widget. It also demonstrates how
    \l {Property aliases}{property aliases} and
    \l {Introduction to the QML Language#Default Properties}{default properties} can be used to collect and
    assemble the child items declared within an \l Item.

    \image qml-tabwidget-example.png
*/

QDoc उदाहरण फ़ाइलों को जेनरेट करने के लिए Qt Project ( .pro ) फ़ाइल को खोजने के लिए इनपुट exampledirs चर में निर्दिष्ट निर्देशिका का उपयोग करेगा। जेनरेट किए गए HTML में फ़ाइल नाम, declarative-ui-components-tabwidget.html । QDoc सभी उदाहरण कोड को भी सूचीबद्ध करेगा।

नोट: उदाहरण का प्रोजेक्ट फ़ाइल निर्देशिका नाम के समान होना चाहिए।