Qt 5.11 - Introduction to QDoc

QDoc का परिचय




qt

QDoc का परिचय

QDoc, Qt Developers द्वारा उपयोग किया जाने वाला एक उपकरण है, जो सॉफ्टवेयर परियोजनाओं के लिए दस्तावेज तैयार करता है। यह प्रोजेक्ट स्रोत फ़ाइलों से QDoc टिप्पणियों को निकालने और फिर इन टिप्पणियों को HTML पृष्ठों या DITA XML दस्तावेज़ों के रूप में प्रारूपित करने का काम करता है। QDoc .cpp फ़ाइलों और .qdoc फ़ाइलों में .qdoc टिप्पणियाँ पाता है। QDoc .h फ़ाइलों में QDoc टिप्पणियों के लिए नहीं दिखता है। एक QDoc टिप्पणी हमेशा विस्मयादिबोधक चिह्न ( ! ) के साथ शुरू होती है। उदाहरण के लिए:

    / *!
        \class QObject
        \brief The QObject class is the base class of all Qt objects.

        \ingroup objectmodel

        \reentrant

        QObject is the heart of the Qt \l{Object Model}. The
        central feature in this model is a very powerful mechanism
        for seamless object communication called \l{signals and
        slots}. You can connect a signal to a slot with connect()
        and destroy the connection with disconnect(). To avoid
        never ending notification loops you can temporarily block
        signals with blockSignals(). The protected functions
        connectNotify() and disconnectNotify() make it possible to
        track connections.

        QObjects organize themselves in \l {Object Trees &
        Ownership} {object trees}. When you create a QObject with
        another object as parent, the object will automatically
        add itself to the parent's \c children() list. The parent
        takes ownership of the object. It will automatically
        delete its children in its destructor. You can look for an
        object by name and optionally type using findChild() or
        findChildren().

        Every object has an objectName() and its class name can be
        found via the corresponding metaObject() (see
        QMetaObject::className()). You can determine whether the
        object's class inherits another class in the QObject
        inheritance hierarchy by using the \c inherits() function.

    ....
* /

ऊपर QDoc टिप्पणी से, QDoc HTML QObject वर्ग संदर्भ पृष्ठ उत्पन्न करता है।

यह मैनुअल बताता है कि अपने स्रोत फ़ाइलों में अच्छे प्रलेखन को एम्बेड करने के लिए QDoc टिप्पणियों में QDoc कमांड का उपयोग कैसे करें। यह भी बताता है कि QDoc कॉन्फ़िगरेशन फ़ाइल कैसे बनाई जाए , जिसे आप कमांड लाइन पर QDoc को पास करेंगे।

QDoc चल रहा है

QDoc प्रोग्राम का नाम qdoc । कमांड लाइन से qdoc चलाने के लिए, इसे एक विन्यास फाइल का नाम दें:

$ ../../bin/qdoc ./config.qdocconf

QDoc एक QDoc कॉन्फ़िगरेशन फ़ाइल के रूप में .qdocconf प्रत्यय को पहचानता है। कॉन्फ़िगरेशन फ़ाइल वह जगह है जहां आप QDoc को बताते हैं कि प्रोजेक्ट स्रोत फ़ाइलों, शीर्ष लेख फ़ाइलों और .qdoc फ़ाइलों को .qdoc । यह भी है कि आप QDoc को किस तरह का आउटपुट जनरेट करते हैं (HTML, DITA XML, ...), और जहां जनरेट किए गए डॉक्यूमेंटेशन को रखना है। कॉन्फ़िगरेशन फ़ाइल में QDoc के लिए अन्य जानकारी भी है।

QDoc कॉन्फ़िगरेशन फ़ाइल कैसे सेट करें , इसके निर्देशों के लिए QDoc कॉन्फ़िगरेशन फ़ाइल देखें।

एकल निष्पादन मोड में QDoc चल रहा है

Qt 5.5 से शुरू होकर, QDoc को चलाने का एक नया तरीका उपलब्ध है जो Qt5 प्रलेखन को 90% तक उत्पन्न करने में लगने वाले समय को कम करता है। QDoc चलाने का नया तरीका एकल निष्पादन मोड है। Qt5 बिल्ड सिस्टम में वर्तमान में एकल निष्पादन मोड उपलब्ध नहीं है, जो अभी भी मानक मोड का उपयोग करता है। एकल निष्पादन मोड केवल तब उपलब्ध होता है जब आप स्वयं QDoc चलाते हैं, जिसे आप अक्सर अपने मॉड्यूल के दस्तावेज़ के रूप में करना चाहते हैं और अन्य Qt मॉड्यूल के साथ अपने दस्तावेज़ को एकीकृत करते हैं।

QDoc को एकल निष्पादन मोड में चलाने के लिए, कमांड लाइन में आंसर -single-exec निष्पादन जोड़ दें और QDoc को एक मास्टर qdocconf फ़ाइल पास करें जो सभी Qt5 मॉड्यूल की qdocconf फ़ाइलों के लिए बस फ़ाइल पथों की सूची है। उदाहरण के लिए:

/Users/me/qt5/qtbase/bin/qdoc -outputdir /Users/me/qt5/qtbase/doc -installdir /Users/me/qt5/qtbase/doc /Users/me/qt5/master.qdocconf -single-exec

Qdocconf फ़ाइल, master.qdocconf , बस Qt5 मॉड्यूल के लिए संसाधित होने वाली qdocconf फ़ाइलों को सूचीबद्ध करता है:

/Users/me/qt5/qtbase/src/corelib/doc/qtcore.qdocconf
/Users/me/qt5/qtbase/src/network/doc/qtnetwork.qdocconf
/Users/me/qt5/qtbase/src/sql/doc/qtsql.qdocconf
/Users/me/qt5/qtbase/src/xml/doc/qtxml.qdocconf
/Users/me/qt5/qtbase/src/testlib/doc/qttestlib.qdocconf
/Users/me/qt5/qtbase/src/concurrent/doc/qtconcurrent.qdocconf
/Users/me/qt5/qtbase/src/gui/doc/qtgui.qdocconf
/Users/me/qt5/qtbase/src/platformheaders/doc/qtplatformheaders.qdocconf
/Users/me/qt5/qtbase/src/widgets/doc/qtwidgets.qdocconf
/Users/me/qt5/qtbase/src/opengl/doc/qtopengl.qdocconf
/Users/me/qt5/qtbase/src/printsupport/doc/qtprintsupport.qdocconf
/Users/me/qt5/qtbase/src/tools/qdoc/doc/config/qdoc.qdocconf
/Users/me/qt5/qtbase/qmake/doc/qmake.qdocconf
/Users/me/qt5/qtsvg/src/svg/doc/qtsvg.qdocconf
/Users/me/qt5/qtxmlpatterns/src/xmlpatterns/doc/qtxmlpatterns.qdocconf
/Users/me/qt5/qtdeclarative/src/qml/doc/qtqml.qdocconf
/Users/me/qt5/qtdeclarative/src/quick/doc/qtquick.qdocconf
/Users/me/qt5/qtquickcontrols/src/controls/doc/qtquickcontrols.qdocconf
/Users/me/qt5/qtquickcontrols/src/layouts/doc/qtquicklayouts.qdocconf
/Users/me/qt5/qtquickcontrols/src/dialogs/doc/qtquickdialogs.qdocconf
/Users/me/qt5/qtmultimedia/src/multimedia/doc/qtmultimedia.qdocconf
/Users/me/qt5/qtmultimedia/src/multimediawidgets/doc/qtmultimediawidgets.qdocconf
/Users/me/qt5/qtactiveqt/src/activeqt/doc/activeqt.qdocconf
/Users/me/qt5/qtsensors/src/sensors/doc/qtsensors.qdocconf
/Users/me/qt5/qtwebkit/Source/qtwebkit.qdocconf
/Users/me/qt5/qttools/src/assistant/help/doc/qthelp.qdocconf
/Users/me/qt5/qttools/src/assistant/assistant/doc/qtassistant.qdocconf
/Users/me/qt5/qttools/src/designer/src/uitools/doc/qtuitools.qdocconf
/Users/me/qt5/qttools/src/designer/src/designer/doc/qtdesigner.qdocconf
/Users/me/qt5/qttools/src/linguist/linguist/doc/qtlinguist.qdocconf
/Users/me/qt5/qtwebkit-examples/doc/qtwebkitexamples.qdocconf
/Users/me/qt5/qtimageformats/src/imageformats/doc/qtimageformats.qdocconf
/Users/me/qt5/qtgraphicaleffects/src/effects/doc/qtgraphicaleffects.qdocconf
/Users/me/qt5/qtscript/src/script/doc/qtscript.qdocconf
/Users/me/qt5/qtscript/src/scripttools/doc/qtscripttools.qdocconf
/Users/me/qt5/qtserialport/src/serialport/doc/qtserialport.qdocconf
/Users/me/qt5/qtdoc/doc/config/qtdoc.qdocconf

क्यों मानक मोड धीमा है

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

जब Qt5 साथ आया, Qt को मॉड्यूल में विभाजित किया गया। तब से, Qt में कई नए मॉड्यूल जोड़े गए हैं। संस्करण 5.5 के अनुसार, Qt5 में 40 से अधिक अलग-अलग मॉड्यूल हैं, प्रत्येक का अपना प्रलेखन है जो अन्य Qt मॉड्यूल के प्रलेखन के लिए (निर्भर करता है) लिंक करता है।

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

मॉड्यूल के प्रलेखन में संभवतः एक या अधिक क्यूटी मॉड्यूल के प्रलेखन के लिए HTML लिंक होंगे। उदाहरण के लिए, अधिकांश Qt5 मॉड्यूल QtCore में प्रलेखन के लिंक होते हैं। जब एक Qt मॉड्यूल में अन्य Qt मॉड्यूल के प्रलेखन में लिंक होते हैं, तो उस मॉड्यूल को उन अन्य Qt मॉड्यूल पर निर्भर करने के लिए कहा जाता है। इसलिए जब QDoc उस मॉड्यूल के लिए उत्पन्न चरण चलाता है, तो उसे उन मॉड्यूल के लिए अनुक्रमणिका फ़ाइलों को भी लोड करना होगा ताकि यह उन सोचों को बना सके।

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

क्यों एकल निष्पादन मोड बहुत तेज़ है

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

QDoc फिर उत्पन्न चरण के लिए प्रत्येक मॉड्यूल को फिर से संसाधित करता है । लेकिन अब QDoc को प्रत्येक मॉड्यूल के स्रोत फ़ाइलों को फिर से पार्स करने की आवश्यकता नहीं है, क्योंकि मॉड्यूल का सिंटैक्स ट्री अभी भी स्मृति में है। न ही QDoc को फिर से आश्रित मॉड्यूल के लिए अनुक्रमणिका फ़ाइलों को पढ़ने की आवश्यकता है, क्योंकि इसमें अभी भी स्मृति में उन मॉड्यूल के लिए वाक्यविन्यास पेड़ हैं। यह प्रलेखन पृष्ठों को उत्पन्न करने के लिए प्रत्येक मॉड्यूल के वाक्यविन्यास पेड़ को पार करने के लिए ही रहता है।

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

QDoc कैसे काम करता है

QDoc कमांड लाइन पर आपके द्वारा निर्दिष्ट कॉन्फ़िगरेशन फ़ाइल को पढ़ने से शुरू होता है। यह बाद के उपयोग के लिए कॉन्फ़िगरेशन फ़ाइल से सभी चर संग्रहीत करता है। इसका उपयोग करने वाले पहले चरों में से एक outputformats । यह चर QDoc को बताता है कि यह कौन सा आउटपुट जेनरेट करेगा। डिफ़ॉल्ट मान HTML है , इसलिए यदि आप अपने कॉन्फ़िगरेशन फ़ाइल में outputformats सेट नहीं करते हैं, तो QDoc HTML आउटपुट उत्पन्न करेगा। यह आमतौर पर आप वैसे भी क्या चाहते हैं, लेकिन आप DITAXML को DITA XML आउटपुट प्राप्त करने के लिए भी निर्दिष्ट कर सकते हैं।

इसके बाद, QDoc headers वेरिएबल और / या headers वैरिएबल के मानों का उपयोग करता है जो आपके प्रोजेक्ट के सभी हेडर फाइल्स को खोजने और पार्स करने के लिए है। QDoc QDoc टिप्पणियों के लिए हेडर फ़ाइलों को स्कैन नहीं करता है। यह उन सभी मदों के मास्टर ट्री बनाने के लिए हेडर फ़ाइलों को पार्स करता है जिन्हें प्रलेखित किया जाना चाहिए, दूसरे शब्दों में, QDoc के लिए QDoc टिप्पणियाँ जो आइटम ढूंढनी चाहिए।

सभी हेडर फ़ाइलों को पार्स करने और डॉक्यूमेंट किए जाने वाले आइटम के मास्टर ट्री के निर्माण के बाद, QDoc अपने प्रोजेक्ट के सभी .cpp और .qdoc फ़ाइलों को खोजने और पार्स करने के लिए sources चर के मान और / या sources के मान का उपयोग करता है। ये QDoc टिप्पणियों के लिए QDoc स्कैन फाइलें हैं। याद रखें कि एक QDoc टिप्पणी एक विस्मयादिबोधक चिह्न के साथ शुरू होती है: / *!

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

अंत में, QDoc मास्टर ट्री का पता लगाता है। प्रत्येक नोड के लिए, यदि नोड ने दस्तावेज़ीकरण संग्रहीत किया है, तो QDoc outputformats चर द्वारा निर्दिष्ट आउटपुट जनरेटर को स्वरूपित चर में कॉन्फ़िगरेशन फ़ाइल में निर्दिष्ट निर्देशिका में प्रलेखन को लिखने के लिए outputdir है।

कमांड प्रकार

QDoc तीन प्रकार के आदेशों की व्याख्या करता है:

टॉपिक कमांड उस तत्व की पहचान करता है जिसे आप दस्तावेज कर रहे हैं, उदाहरण के लिए C ++ वर्ग, फ़ंक्शन, प्रकार, या पाठ का एक अतिरिक्त पृष्ठ जो किसी अंतर्निहित C ++ तत्व को मैप नहीं करता है।

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

मार्कअप कमांड्स QDoc को बताती हैं कि दस्तावेज़ में टेक्स्ट और छवि तत्वों को कैसे प्रस्तुत किया जाना चाहिए, या दस्तावेज़ की रूपरेखा संरचना के बारे में।