Qt 5.11 - C++ Documentation Style

C ++ डॉक्यूमेंटेशन स्टाइल




qt

C ++ डॉक्यूमेंटेशन स्टाइल

प्रलेखन उत्पन्न करने के लिए, QDoc स्रोत कोड के माध्यम से जाता है और कक्षाओं जैसे C ++ प्रकारों के लिए प्रलेखन उत्पन्न करता है। QDoc तब सदस्य कार्यों, गुणों और अन्य प्रकारों को उपयुक्त वर्ग में जोड़ता है।

ध्यान दें कि दस्तावेज़ीकरण कार्यान्वयन फ़ाइलों में होना चाहिए जैसे .cpp

कक्षा का प्रलेखन

प्रथम तर्क के रूप में \class कमांड और \class के नाम का उपयोग करके क्लास डॉक्यूमेंटेशन तैयार किया जाता है।

/*!
    \class QCache
    \brief The QCache class is a template class that provides a cache.

    \ingroup tools
    \ingroup shared

    \reentrant

    QCache\<Key, T\> defines a cache that stores objects of type T
    associated with keys of type Key. For example, here's the
    definition of a cache that stores objects of type Employee
    associated with an integer key:

    \snippet code/doc_src_qcache.cpp 0

    Here's how to insert an object in the cache:

    \snippet code/doc_src_qcache.cpp 1

    ... detailed description ommitted

    \sa QPixmapCache, QHash, QMap
*/

संदर्भ आदेश वर्ग के बारे में जानकारी जोड़ते हैं, जैसे कि इसका मॉड्यूल या कौन सा संस्करण वर्ग जोड़ा गया था।

कुछ सामान्य संदर्भ आदेश हैं:

  • \brief - वर्ग का संक्षिप्त विवरण (अनिवार्य)
  • \since - जिस संस्करण में वर्ग जोड़ा गया था (अनिवार्य)
  • \internal - वर्ग को आंतरिक के रूप में चिह्नित करता है। सार्वजनिक एपीआई प्रलेखन में आंतरिक कक्षाएं दिखाई नहीं देती हैं।

संक्षिप्त और विस्तृत विवरण

संक्षिप्त विवरण \brief आदेश के साथ चिह्नित है और यह वर्ग के उद्देश्य या कार्यक्षमता को संक्षेप में प्रस्तुत करने के लिए है। C ++ क्लासेस के लिए, QDoc क्लास लेगा और क्लास के लिए एनोटेट जानकारी बनाएगा। एनोटेट जानकारी उन सूचियों और तालिकाओं में दिखाई देती है जो कक्षा प्रदर्शित करती हैं।

C ++ संक्षिप्त के साथ शुरू होना चाहिए:

"The <C++ class name> class"

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

सदस्य कार्य

आमतौर पर, फ़ंक्शन प्रलेखन तुरंत .cpp फ़ाइल में फ़ंक्शन के कार्यान्वयन से पहले होता है। फ़ंक्शन प्रलेखन के लिए जो कार्यान्वयन के तुरंत ऊपर नहीं है, \fn की आवश्यकता है।

/*!
  \fn QString &QString::remove(int position, int n)

  Removes \a n characters from the string, starting at the given \a
  position index, and returns a reference to the string.

  If the specified \a position index is within the string, but \a
  position + \a n is beyond the end of the string, the string is
  truncated at the specified \a position.

  \snippet qstring/main.cpp 37

  \sa insert(), replace()
*/
QString &QString::remove(int pos, int len)

फ़ंक्शन दस्तावेज़ीकरण एक क्रिया के साथ शुरू होता है, जो फ़ंक्शन को निष्पादित करने वाले ऑपरेशन का संकेत देता है। यह कंस्ट्रक्टर और डिस्ट्रक्टर्स पर भी लागू होता है।

फ़ंक्शन प्रलेखन के लिए कुछ सामान्य क्रियाएं:

  • "निर्माण ..." - निर्माणकर्ताओं के लिए
  • "विनाशकारी ..." - विनाशकों के लिए
  • "रिटर्न ..." - गौण कार्यों के लिए

फ़ंक्शन दस्तावेज़ को दस्तावेज़ होना चाहिए:

  • वापसी प्रकार
  • पैरामीटर
  • कार्यों की क्रिया

\a _ कमांड में प्रलेखन में \a कमांड पैरामीटर को चिह्नित करता है। रिटर्न टाइप डॉक्यूमेंटेशन को टाइप डॉक्यूमेंटेशन से लिंक होना चाहिए या बूलियन वैल्यू के मामले में \c कमांड से चिह्नित किया जाना चाहिए।

/*!
    Returns \c true if a QScroller object was already created for \a target; \c false otherwise.

    \sa scroller()
*/
bool QScroller::hasScroller(QObject *target)

गुण

प्रॉपर्टी डॉक्यूमेंटेशन रीड फंक्शन के कार्यान्वयन से तुरंत ऊपर रहता है। गुण के लिए विषय कमांड \property

/*!
    \property QVariantAnimation::duration
    \brief the duration of the animation

    This property describes the duration in milliseconds of the
    animation. The default duration is 250 milliseconds.

    \sa QAbstractAnimation::duration()
 */
int QVariantAnimation::duration() const

संपत्ति प्रलेखन आमतौर पर "यह संपत्ति ..." से शुरू होता है, लेकिन ये वैकल्पिक अभिव्यक्ति हैं:

  • "यह संपत्ति रखती है ..."
  • "इस संपत्ति का वर्णन है ..."
  • "यह संपत्ति प्रतिनिधित्व करती है ..."
  • "वापस लौटता true जब true ... और जब false ..." - पढ़े जाने वाले गुणों के लिए।
  • "सेट ..." - एक प्रकार को कॉन्फ़िगर करने वाले गुणों के लिए।

संपत्ति प्रलेखन में शामिल होना चाहिए:

  • संपत्ति का विवरण और व्यवहार
  • संपत्ति के लिए स्वीकृत मूल्य
  • संपत्ति का डिफ़ॉल्ट मूल्य

functions समान, डिफ़ॉल्ट प्रकार को \c कमांड के साथ जोड़ा या चिह्नित किया जा सकता है।

मूल्य श्रेणी शैली का एक उदाहरण है:

ये मान 0.0R (नो ब्लर) से लेकर मैक्सिमेरियस (अधिकतम ब्लर) तक होते हैं। डिफ़ॉल्ट रूप से, संपत्ति 0.0 (कोई धब्बा) पर सेट नहीं है।

सिग्नल, नोटिफ़ायर और स्लॉट्स

सिग्नल, नोटिफ़ायर और स्लॉट के लिए विषय कमांड \fn । सिग्नल प्रलेखन स्थिति जब वे ट्रिगर या उत्सर्जित होते हैं।

/*!
  \fn QAbstractTransition::triggered()

  This signal is emitted when the transition has been triggered (after
  onTransition() has been called).
*/

सिग्नल प्रलेखन आम तौर पर "यह संकेत तब शुरू होता है जब ..." से शुरू होता है। यहाँ वैकल्पिक शैली हैं:

  • "यह संकेत तब शुरू होता है जब ..."
  • "जब ट्रिगर ..."
  • "जब उत्सर्जित ..."

स्लॉट्स या नोटिफ़ायर के लिए, किसी सिग्नल द्वारा निष्पादित या ट्रिगर किए जाने की स्थिति को प्रलेखित किया जाना चाहिए।

  • "जब ...
  • "यह स्लॉट तब निष्पादित किया जाता है जब ..."

उन संपत्तियों के लिए, जिनके पास अतिभारित सिग्नल हैं, QDoc ने ओवरलोड किए गए नोटिफ़ायर को एक साथ समूहित किया। एक नोटिफ़ायर या सिग्नल के विशिष्ट संस्करण को संदर्भित करने के लिए, बस संपत्ति को देखें और उल्लेख करें कि नोटिफ़ायर के विभिन्न संस्करण हैं।

/*!
\property QSpinBox::value
\brief the value of the spin box

setValue() will emit valueChanged() if the new value is different
from the old one. The \l{QSpinBox::}{value} property has a second notifier
signal which includes the spin box's prefix and suffix.
*/

एनम, नाम स्थान और अन्य प्रकार

Enums, नाम स्थान और मैक्रोज़ के पास अपने प्रलेखन के लिए एक विषय कमांड है :

इन प्रकारों के लिए भाषा शैली का उल्लेख है कि वे एक एनम या मैक्रो हैं और प्रकार के विवरण के साथ जारी हैं।

गणना के लिए, मानों को सूचीबद्ध करने के लिए \value कमांड है। क्यूमोक एनम के लिए मूल्यों की एक तालिका बनाता है।

/*!
    \enum QSql::TableType

    This enum type describes types of SQL tables.

    \value Tables  All the tables visible to the user.
    \value SystemTables  Internal tables used by the database.
    \value Views  All the views visible to the user.
    \value AllTables  All of the above.
*/