adminschool.net wiki

사용자 도구

사이트 도구

추적:
develop:doc:doxygen:docblocks

차이

문서의 선택한 두 판 사이의 차이를 보여줍니다.

차이 보기로 링크

양쪽 이전 판 이전 판
다음 판 		이전 판
develop:doc:doxygen:docblocks [2011/07/19 10:23]
starlits 		develop:doc:doxygen:docblocks [2011/07/19 11:59] (현재)
starlits
줄 62: 줄 62:
 //! Detailed description  //! Detailed description 
 //! starts here. //! starts here.
-</code> 상세설명을 포함하고 있는 블럭을 간단히 설명하기 위해서 마지막 예에서 빈라인을 이용하였다. \\ 이경우에는 JAVADOC_AUTOBRIEF 옵션이 NO 되어있어야 합니다.+</code> 상세설명을 포함하고 있는 블럭을 간단히 설명하기 위해서 마지막 예에서 빈라인을 이용하였다. \\ 이경우에는 <color blue>JAVADOC_AUTOBRIEF</color> 옵션이 NO 이어야 한다.
  
 ==== 부가설명 ==== ==== 부가설명 ====
줄 137: 줄 137:
     int (*handler)(int a,int b);     int (*handler)(int a,int b);
 }; };
-</code> Click [[http://www.stack.nl/~dimitri/doxygen/examples/qtstyle/html/class_test.html | here ]] for the corresponding HTML documentation that is generated by doxygen.  +</code> doxygen에 의해 생성되는 해당 HTML 문서를 보려면 [[http://www.stack.nl/~dimitri/doxygen/examples/qtstyle/html/class_test.html |여기]]를 클릭하십시오. 
- +  - 멀티 라인 주석 블록에 대한 자세한 설명을 포함하는 반면 한 라인 주석은 간단한 설명이 포함되어 있습니다. 
- +  - 간략설명(brief descriptions)은 class, namespace, file 의 멤버 개요가 포함되어 있으며 작은 기울임꼴 글꼴을 사용하여 인쇄됩니다 (이 설명은 설정파일에서 BRIEF_MEMBER_DESC 값이 NO로 숨길 수 있습니다.) \\ 기본적으로 간략설명은 상세설명의 첫문장에 옵니다. (그러나 REPEAT_BRIEF 값을 NO로 변경할 수 있습니다). \\ 간략설명과 상세설명 모두 Qt 스타일의 옵션입니다.  
-The one-line comments contain a brief description, whereas the multi-line comment blocks contain a more detailed description.  +  - 기본적으로 JavaDoc 스타일의 문서 블록은 Qt는 스타일 문서 블록과 같은 방식으로 동작합니다. JavaDoc은 명시적으로 문서의 첫번째 블록에 간략설명되지 않아도 상관없다.(This is not according the JavaDoc specification however, where the first sentence of the documentation block is automatically treated as a brief description.) 이 동작을 사용하려면 JAVADOC_AUTOBRIEF 을 YES로 설정해야 한다. \\ 만약 이 옵션을 활성화하고 끝나지 않은 문장의 중간에 점(dot)을 넣으려는 경우에는, 점뒤에 백슬래시(backslash)와 공간(space)를 붙여야 합니다. 그 예이다: <code>
- +
- +
-The brief descriptions are included in the member overview of a class, namespace or file and are printed using a small italic font (this description can be hidden by setting BRIEF_MEMBER_DESC to NO in the config file). By default the brief descriptions become the first sentence of the detailed descriptions (but this can be changed by setting the REPEAT_BRIEF tag to NO). Both the brief and the detailed descriptions are optional for the Qt style.  +
- +
- +
-By default a JavaDoc style documentation block behaves the same way as a Qt style documentation block. This is not according the JavaDoc specification however, where the first sentence of the documentation block is automatically treated as a brief description. To enable this behaviour you should set JAVADOC_AUTOBRIEF to YES in the configuration file. If you enable this option and want to put a dot in the middle of a sentence without ending it, you should put a backslash and a space after it. Here is an example: <code>+
 /** Brief description (e.g.\ using only a few words). Details follow. */ /** Brief description (e.g.\ using only a few words). Details follow. */
 </code> </code>
- +  - Here is the same piece of code as shown above, this time documented using the JavaDoc style and JAVADOC_AUTOBRIEF set to YES: <code>
-Here is the same piece of code as shown above, this time documented using the JavaDoc style and JAVADOC_AUTOBRIEF set to YES: <code>+
 /** /**
  *  A test class. A more elaborate class description.  *  A test class. A more elaborate class description.
줄 216: 줄 209:
        int (*handler)(int a,int b);        int (*handler)(int a,int b);
 }; };
-</code> Click [[http://www.stack.nl/~dimitri/doxygen/examples/jdstyle/html/class_test.html | here]] for the corresponding HTML documentation that is generated by doxygen.  +</code> doxygen에 의해 생성되는 해당 HTML 문서를 보려면 [[http://www.stack.nl/~dimitri/doxygen/examples/jdstyle/html/class_test.html |여기]]를 클릭하십시오. 
- +  - 대부분의 다른 문서와 달리 doxygen은 정의 앞에 member의 문서(global functions 포함)을 넣을 수 있다. \\ 이 방법을 통해서 문서를 헤더파일 대신 소스파일에 놓을 수 있다. \\ 이 방법은 header를 컴팩트(compact)하게 하고, 문서를 더 많이 직접접근(direct access)하게 하는 맴버의 시행(implementer)을 허락한다. \\ 간략설명은 선언(declaration)전엔 놓일 수 있고, 상세설명은 맴버정의(member definition)전에 놓일 수 있게 절충(compromise)할 수 있다.
- +
-Unlike most other documentation systems, doxygen also allows you to put the documentation of members (including global functions) in front of the definition. This way the documentation can be placed in the source file instead of the header file. This keeps the header file compact, and allows the implementer of the members more direct access to the documentation. As a compromise the brief description could be placed before the declaration and the detailed description before the member definition. +
  
 ===== Putting documentation after members ===== ===== Putting documentation after members =====
줄 239: 줄 230:
 int var; ///< Brief description after the member int var; ///< Brief description after the member
 </code> </code>
- +  - Note that these blocks have the same structure and meaning as the special comment blocks in the previous section only the < indicates that the member is located in front of the block instead of after the block.  
-Note that these blocks have the same structure and meaning as the special comment blocks in the previous section only the < indicates that the member is located in front of the block instead of after the block.  +  - Here is an example of the use of these comment blocks: <code>
- +
-Here is an example of the use of these comment blocks: <code>+
 /*! A test class */ /*! A test class */
  
줄 264: 줄 253:
  
 ==== 주의사항 ==== ==== 주의사항 ====
-These blocks can only be used to document members and parameters. They cannot be used to document files, classes, unions, structs, groups, namespaces and enums themselves. Furthermore, the structural commands mentioned in the next section (like \class) are ignored inside these comment blocks. +  - These blocks can only be used to document members and parameters. They cannot be used to document files, classes, unions, structs, groups, namespaces and enums themselves. Furthermore, the structural commands mentioned in the next section (like \class) are ignored inside these comment blocks. 
  
  
 ===== Documentation at other places ===== ===== Documentation at other places =====
-So far we have assumed that the documentation blocks are always located in front of the declaration or definition of a file, class or namespace or in front or after one of its members. Although this is often comfortable, there may sometimes be reasons to put the documentation somewhere else. For documenting a file this is even required since there is no such thing as "in front of a file". Doxygen allows you to put your documentation blocks practically anywhere (the exception is inside the body of a function or inside a normal C style comment block). The price you pay for not putting the documentation block before (or after) an item is the need to put a structural command inside the documentation block, which leads to some duplication of information.  +  - So far we have assumed that the documentation blocks are always located in front of the declaration or definition of a file, class or namespace or in front or after one of its members. Although this is often comfortable, there may sometimes be reasons to put the documentation somewhere else. For documenting a file this is even required since there is no such thing as "in front of a file". Doxygen allows you to put your documentation blocks practically anywhere (the exception is inside the body of a function or inside a normal C style comment block). The price you pay for not putting the documentation block before (or after) an item is the need to put a structural command inside the documentation block, which leads to some duplication of information.  
- +  - uctural commands (like all other commands) start with a backslash (\), or an at-sign (@) if you prefer JavaDoc style, followed by a command name and one or more parameters. For instance, if you want to document the class Test in the example above, you could have also put the following documentation block somewhere in the input that is read by doxygen: <code>
-uctural commands (like all other commands) start with a backslash (\), or an at-sign (@) if you prefer JavaDoc style, followed by a command name and one or more parameters. For instance, if you want to document the class Test in the example above, you could have also put the following documentation block somewhere in the input that is read by doxygen: <code>+
 /*! \class Test /*! \class Test
     \brief A test class.     \brief A test class.
줄 277: 줄 265:
 */ */
 </code> </code>
- +  - Here the special command \class is used to indicate that the comment block contains documentation for the class Test. Other structural commands are: <code>
- +
-Here the special command \class is used to indicate that the comment block contains documentation for the class Test. Other structural commands are: <code>+
 \struct to document a C-struct.  \struct to document a C-struct. 
 \union to document a union.  \union to document a union. 
줄 291: 줄 277:
 \interface to document an IDL interface.  \interface to document an IDL interface. 
 </code> See section [[http://www.stack.nl/~dimitri/doxygen/commands.html | Special Commands]] for detailed information about these and many other commands. </code> See section [[http://www.stack.nl/~dimitri/doxygen/commands.html | Special Commands]] for detailed information about these and many other commands.
- +  - To document a member of a C++ class, you must also document the class itself. The same holds for namespaces. To document a global C function, typedef, enum or preprocessor definition you must first document the file that contains it (usually this will be a header file, because that file contains the information that is exported to other source files).  
- +  - Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a <code>
-To document a member of a C++ class, you must also document the class itself. The same holds for namespaces. To document a global C function, typedef, enum or preprocessor definition you must first document the file that contains it (usually this will be a header file, because that file contains the information that is exported to other source files).  +
- +
- +
- +
-Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a <code>+
 /*! \file */  /*! \file */ 
 </code> 또는 <code> </code> 또는 <code>
  /** @file */   /** @file */ 
 </code> </code>
- +  - Here is an example of a C header named structcmd.h that is documented using structural commands:  <code>
-Here is an example of a C header named structcmd.h that is documented using structural commands:  <code>+
 /*! \file structcmd.h /*! \file structcmd.h
     \brief A Documented file.     \brief A Documented file.
줄 362: 줄 342:
 int read(int,char *,size_t); int read(int,char *,size_t);
 </code> Click [[http://www.stack.nl/~dimitri/doxygen/examples/structcmd/html/structcmd_8h.html | here]] for the corresponding HTML documentation that is generated by doxygen.  </code> Click [[http://www.stack.nl/~dimitri/doxygen/examples/structcmd/html/structcmd_8h.html | here]] for the corresponding HTML documentation that is generated by doxygen. 
- +  - Because each comment block in the example above contains a structural command, all the comment blocks could be moved to another location or input file (the source file for instance), without affecting the generated documentation. The disadvantage of this approach is that prototypes are duplicated, so all changes have to be made twice! Because of this you should first consider if this is really needed, and avoid structural commands if possible. I often receive examples that contain \fn command in comment blocks which are place in front of a function. This is clearly a case where the \fn command is redundant and will only lead to problems. 
-Because each comment block in the example above contains a structural command, all the comment blocks could be moved to another location or input file (the source file for instance), without affecting the generated documentation. The disadvantage of this approach is that prototypes are duplicated, so all changes have to be made twice! Because of this you should first consider if this is really needed, and avoid structural commands if possible. I often receive examples that contain \fn command in comment blocks which are place in front of a function. This is clearly a case where the \fn command is redundant and will only lead to problems. +
  
  
develop/doc/doxygen/docblocks.1311038624.txt.gz · 마지막으로 수정됨: 2011/07/19 10:23 저자 starlits

문서 도구

별도로 명시하지 않을 경우, 이 위키의 내용은 다음 라이선스에 따라 사용할 수 있습니다: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki