C++ 문서 스타일

문서를 생성하기 위해 QDoc은 소스 코드를 검토하여 클래스와 같은 C++ 유형에 대한 문서를 생성합니다. 그런 다음 QDoc은 멤버 함수, 속성 및 기타 유형을 적절한 클래스에 연결합니다.

문서는 .cpp 과 같은 구현 파일에 있어야 합니다.

클래스 문서

클래스 문서는 \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 omitted

    \sa QPixmapCache, QHash, QMap
*/

컨텍스트 명령은 모듈이나 클래스가 추가된 버전 등 클래스에 대한 정보를 추가합니다.

몇 가지 일반적인 컨텍스트 명령은 다음과 같습니다:

  • \brief - 클래스의 간단한 설명 (필수)
  • \이후 - 클래스가 추가된 버전 (필수)
  • \내부 - 클래스를 내부로 표시합니다. 내부 클래스는 공개 API 문서에 표시되지 않습니다.

간략한 설명과 자세한 설명

간략한 설명은 \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)

함수 문서는 함수가 수행하는 작업을 나타내는 동사로 시작합니다. 이는 생성자 및 소멸자에도 적용됩니다.

함수 문서에 자주 사용되는 동사는 다음과 같습니다:

  • "생성하다..." - 생성자의 경우
  • "파괴..." - 소멸자의 경우
  • "Returns..." - 접근자 함수의 경우

함수 문서에는 반드시

  • 반환 유형
  • 매개변수
  • 함수의 동작

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 및...일 때 false 을 반환합니다." - 읽은 속성에 대해.
  • "이 속성은..." - 유형을 구성하는 속성의 경우.

프로퍼티 문서에는 다음이 포함되어야 합니다:

  • 속성에 대한 설명 및 동작
  • 속성에 허용되는 값
  • 속성의 기본값

함수와 마찬가지로 기본 유형은 \c 명령으로 링크하거나 표시할 수 있습니다.

값 범위 스타일의 예는 다음과 같습니다:

값 범위는 0.0(흐림 없음)에서 maximumRadius(최대 흐림)까지입니다. 기본적으로 이 속성은 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.
*/

열거형, 네임스페이스 및 기타 유형

열거형, 네임스페이스 및 매크로에는 해당 문서에 대한 주제 명령어가 있습니다:

이러한 유형의 언어 스타일은 열거형 또는 매크로임을 언급하고 유형 설명과 함께 이어집니다.

열거형의 경우 \value 명령은 값을 나열하는 데 사용됩니다. QDoc은 열거형에 대한 값 테이블을 만듭니다.

/*!
    \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.
*/

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.