Qt 5.11 - Writing Documentation

लेखन दस्तावेज़




qt

लेखन दस्तावेज़

QDoc टिप्पणियाँ

दस्तावेज़ीकरण QDoc टिप्पणियों में निहित है, जो * * द्वारा सीमांकित है! और * / टिप्पणियाँ। ध्यान दें कि ये C ++, QML और जावास्क्रिप्ट में मान्य टिप्पणियां हैं।

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

QDoc C ++ टिप्पणियों को देखने के लिए C ++ और QML फ़ाइलों को पार्स करेगा। एक निश्चित फ़ाइल प्रकार को स्पष्ट रूप से छोड़ने के लिए, इसे configuration फ़ाइल से छोड़ दें।

QDoc कमांड्स

QDoc प्रलेखन के बारे में जानकारी प्राप्त करने के लिए आदेशों का उपयोग करता है। Topic कमांड प्रलेखन तत्व के प्रकार को निर्धारित करते हैं, context कमांड एक विषय के बारे में संकेत और जानकारी प्रदान करते हैं, और markup कमांड इस बात की जानकारी प्रदान करते हैं कि QDoc को दस्तावेज़ के टुकड़े को कैसे प्रारूपित करना चाहिए।

QDoc विषय

प्रत्येक qdoc टिप्पणी में एक विषय प्रकार होना चाहिए। एक विषय इसे अन्य विषयों से अलग करता है। विषय प्रकार निर्दिष्ट करने के लिए, कई विषय कमांड में से एक का उपयोग करें।

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

विषय आदेशों का उदाहरण:

  • \enum - गणन प्रलेखन के लिए
  • \class - सी ++ वर्ग प्रलेखन के लिए
  • \qmltype - QML प्रकार के दस्तावेज़ के लिए
  • एक पृष्ठ बनाने के लिए \page -।

\page कमांड उन लेखों को बनाने के लिए है जो स्रोत प्रलेखन का हिस्सा नहीं हैं। कमांड दो तर्कों को भी स्वीकार कर सकता है: लेख का फ़ाइल नाम और प्रलेखन प्रकार। संभावित प्रकार हैं:

  • howto
  • overview
  • tutorial
  • faq
  • article - डिफ़ॉल्ट जब कोई प्रकार नहीं है
/*!
    \page altruism-faq.html faq
    \title Altruism Frequently Asked Questions

    \brief All the questions about altruism, answered.

    ...
*/

विषय कमांड पृष्ठ पर सभी उपलब्ध विषय कमांड के बारे में जानकारी होती है।

विषय संबंधी प्रसंग

प्रसंग आदेश QDoc को विषय के संदर्भ के बारे में संकेत देते हैं। उदाहरण के लिए, यदि C ++ फ़ंक्शन अप्रचलित है, तो इसे अप्रचलित \obsolete कमांड के साथ चिह्नित किया जाना चाहिए। इसी तरह, पेज नेविगेशन और पेज शीर्षक QDoc को अतिरिक्त पेज की जानकारी देते हैं।

QDoc इन संदर्भों के लिए अतिरिक्त लिंक या पेज बनाएगा। उदाहरण के लिए, \group कमांड का उपयोग करके एक समूह बनाया जाता है और सदस्यों के पास \ingroup कमांड होती है। समूह नाम को एक तर्क के रूप में आपूर्ति की जाती है।

प्रसंग कमांड पृष्ठ में सभी उपलब्ध संदर्भ आदेशों की एक सूची है।

प्रलेखन मार्कअप

QDoc अन्य मार्कअप या प्रलेखन टूल के समान पाठ का मार्कअप कर सकता है। QDoc टेक्स्ट के एक सेक्शन को बोल्ड में चिह्नित कर सकता है, जब टेक्स्ट को \b कमांड के साथ चिह्नित किया जाता है।

\b{This} text will be in \b{bold}.

मार्कअप कमांड पृष्ठ में उपलब्ध मार्कअप कमांड की पूरी सूची है।

प्रलेखन के एनाटॉमी

अनिवार्य रूप से, QDoc के लिए एक पेज बनाने के लिए, कुछ आवश्यक सामग्री मौजूद होनी चाहिए।

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

Qt में, QVector3D क्लास को निम्नलिखित QDoc टिप्पणी के साथ प्रलेखित किया गया था:

/*!
    \class QVector3D
    \brief The QVector3D class represents a vector or vertex in 3D space.
    \since 4.6
    \ingroup painting-3D

    Vectors are one of the main building blocks of 3D representation and
    drawing.  They consist of three coordinates, traditionally called
    x, y, and z.

    The QVector3D class can also be used to represent vertices in 3D space.
    We therefore do not need to provide a separate vertex class.

    \note By design values in the QVector3D instance are stored as \c float.
    This means that on platforms where the \c qreal arguments to QVector3D
    functions are represented by \c double values, it is possible to
    lose precision.

    \sa QVector2D, QVector4D, QQuaternion
*/

इसका एक निर्माता है, QVector3D::QVector3D (), जिसे निम्नलिखित QDoc3 के साथ प्रलेखित किया गया था:

/*!
    \fn QVector3D::QVector3D(const QPoint& point)

    Constructs a vector with x and y coordinates from a 2D \a point, and a
    z coordinate of 0.
*/

अलग-अलग फाइलों में अलग-अलग टिप्पणियाँ रह सकती हैं और QDoc उन्हें उनके विषय और उनके संदर्भ के आधार पर एकत्रित करेगा। स्निपेट्स से परिणामी प्रलेखन QVector3D वर्ग प्रलेखन में उत्पन्न होता है।

ध्यान दें कि यदि दस्तावेज़ तुरंत स्रोत कोड में फ़ंक्शन या वर्ग से पहले आता है, तो उसे एक विषय रखने की आवश्यकता नहीं है। QDoc यह मान लेगा कि कोड के ऊपर प्रलेखन उस कोड के लिए दस्तावेज है।

एक लेख \page कमांड का उपयोग करके बनाया गया है। पहला तर्क HTML फ़ाइल है जिसे QDoc बनाएगा। विषय को संदर्भ आदेश, \ शीर्षक और \ अगले पृष्ठ आदेशों के साथ पूरक किया गया है। कई अन्य QDoc कमांड हैं जैसे कि \list कमांड।

/*!
    \page generic-guide.html
    \title Generic QDoc Guide
    \nextpage Creating QDoc Configuration Files
    There are three essential materials for generating documentation with qdoc:

    \list
        \li \c qdoc binary
        \li \c qdocconf configuration files
        \li \c Documentation in \c C++, \c QML, and \c .qdoc files
    \endlist
*/

विषय कमांड पर अनुभाग कई अन्य प्रकार के विषयों पर एक अवलोकन देता है।