doxygen을 사용하여 코드를 문서화하기 위한 최고의 팁은 무엇입니까?
우리 팀은 공개 API 헤더에 특히 주의를 기울이면서 doxygen을 사용하여 C 코드를 문서화하기 시작했습니다.doxygen에는 많은 유연성과 다양한 특수 명령어가 있는 것으로 보이는데, 이는 훌륭하지만 시행착오 없이 무엇이 좋고 무엇이 나쁜지는 명확하지 않습니다.
코드를 표시하는 가장 좋아하는 방법은 무엇이며, 반드시 해야 할 일과 하지 말아야 할 일은 무엇입니까?
투표를 용이하게 하기 위해 답변당 1개씩 최고의 팁을 제공하십시오.
저는 나머지 팀원들이 시작할 수 있도록 템플릿을 제공하는 것을 포함하여 API 문서에 대한 전체적인 접근 방식을 정의하고자 합니다.지금까지 저는 다음과 같은 것을 가지고 있습니다.
/**
* @file example_action.h
* @Author Me (me@example.com)
* @date September, 2008
* @brief Brief description of file.
*
* Detailed description of file.
*/
/**
* @name Example API Actions
* @brief Example actions available.
* @ingroup example
*
* This API provides certain actions as an example.
*
* @param [in] repeat Number of times to do nothing.
*
* @retval TRUE Successfully did nothing.
* @retval FALSE Oops, did something.
*
* Example Usage:
* @code
* example_nada(3); // Do nothing 3 times.
* @endcode
*/
boolean example(int repeat);
파일 이름을 다음 파일에 쓸 필요가 없습니다.@file읽습니다.", doxygen은 파일 이름을 읽습니다.을 쓸 때는 파일 을 바꿀 때 파일 해야 한다는 입니다.@file지시도 마찬가지입니다.
» @author그리고.@date소스 제어 시스템이 누군가가 파일을 수동으로 편집하는 것보다 훨씬 더 잘 하기 때문에 정보는 또한 대부분 쓸모가 없습니다.
당신은 또한 쓸 필요가 없습니다.@brief다음 Doxygen 구문을 사용하고 doxygen 구성에서 JAVADOC_AUTOBRIEF를 활성화하는 경우:
/*! Short Description on the first line
Detailed description...
...
*/
void foo(void) {}
그@name기능에 대한 지시는 또한 대부분 100% 중복되며 완전히 쓸모가 없습니다. Doxygen이 아닌 합니다.@name.
@mainpage를 사용하여 설명하는 홈 페이지를 작성합니다(이 목적을 위해 별도의 헤더 파일에).예에 나와 있는 것처럼 주요 클래스/기능 및 모듈에 대한 가이드로 만드는 것을 고려합니다.
다른 샘플
위에 링크된 mainoofile doxygen 콘텐츠를 다시 온라인으로 가져오는 동안, Markdown 형식을 사용한 현재 클라이언트 작업의 예를 들어 보겠습니다.인 "" 에 적합한 "Markdown" 페이지(settings)를할 수 . 이는 일반적인 경우에 적합합니다.readme.md파일이 오픈 소스 프로젝트에 포함되어 있습니다.
Lingopal
========
Developer Documentation started when Andy Dent took over support in May 2014.
There are a number of pages in Markdown format which explain key aspects:
- @ref doc/LingopalBuilding.md
- @ref doc/LingopalSigning.md
- @ref doc/LingopalDatabases.md
- @ref doc/LingopalExternals.md
See the <a href="pages.html">Related Pages list for more.</a>
-------------
_Note_
These pages, whilst readable by themselves, are designed to be run through the [Doxygen](http://www.doxygen.com) code documentation engine which builds an entire local cross-referenced set of docs. It uses a minor [extension of Markdown formatting.](http://www.stack.nl/~dimitri/doxygen/manual/markdown.html)
The settings to generate the documentation are `Lingopal.doxy` and `LingopalDocOnly.doxy`. The latter is used for quick re-generation of just these additional pages.
그룹을 사용하여 코드를 모듈로 구성합니다.
스택 오버플로의 태그와 같은 의미 태그를 제공하는 데 사용할 수 있도록 거의 모든 항목을 여러 그룹에 넣을 수 있습니다.예를 들어 지정된 플랫폼과 관련된 태그를 지정할 수 있습니다.
또한 RB2Doxy 샘플 출력에 표시된 것처럼 그룹을 사용하여 IDE 내의 폴더 계층 구조를 일치시킬 수 있습니다.
그룹은 중첩될 때 잘 작동합니다. 저는 OOFILE 소스에 대한 큰 예제를 가지고 있습니다.
내 코드에서 사용하는 일부 명령:
\todo { paragraph describing what is to be done }작업관리를 추적하는 데 유용한 페이지는 작업관리 목록을 포함하는 최종 문서에 작성됩니다.\c <word>타자기 글꼴을 사용하여 인수를 표시합니다.코드 단어를 나타낼 때 사용합니다.이 예에서는 "TRUE"와 "FALSE" 앞에 사용합니다.\a , \warning , \see자세한 내용은 http://www.stack.nl/ ~dimitri/doxygen/dlls.dlls#cmdc를 참조하십시오.
좋은 "베스트 프랙티스"(항상 달성할 수 있는 것은 아니지만)는 모든 API에 대해 짧은 작업 예제를 제공하고 \includeelineo(또는 줄 번호가 없는 경우 \include)를 사용하여 도움말로 끌어오는 것입니다.사용자가 이해할 수 있도록 작성된 경우(즉, 더 큰 테스트 하네스에 연결되지 않음) 단위 테스트가 될 수 있습니다.좋은 부작용으로, API를 변경하면 샘플이 깨지기 때문에 최신 상태로 유지해야 합니다.
당신은 API를 말로 설명할 수 있지만, 그것을 사용하는 방법을 이해하기 위해 실제 코드를 보는 것만큼 좋은 것은 없습니다.
고해상도 화면에서 코드를 편집하면서 Doxygen 명령의 백슬래시 사용에서 @ 접두사로 전환했습니다.그렇게 시끄러운 백슬래시는 이제 Doxygen 명령을 이해하기에 너무 어렵다는 것을 알게 되었습니다.
만약 당신의 팀이 그러한 중량감 있는 템플릿을 따를 것이라고 확신한다면, 좋아요, 그림과 같이 사용하세요.
그렇지 않으면 JavaDoc처럼 보입니다.Doxygen의 좋은 점 중 하나는 이렇게 강력한 마크업을 사용하지 않고도 작업을 얼마나 잘하느냐 하는 것입니다.@name을(를) 사용할 필요가 없으며, JAVADOC_AUTOBRIEF 설정과 함께 @brief를 건너뛸 수 있습니다. 의견의 첫 줄이 합리적인 간단한 설명인지 확인하십시오.
저는 문서를 집행하고 사람들이 중요한 가치를 추가할 때만 주석을 추가하도록 권장하는 것보다 설명적인 이름을 선호합니다.그렇게 하면, 귀중한 논평들이 모든 소음에 의해 지워지지 않습니다.
코드에 버그가 있거나 버그가 발견되면 다음과 같이 코드에 태그를 지정할 수 있습니다.
/** @bug The text explaining the bug */
그런 다음 doxygen을 실행하면 작업관리 목록과 같은 목록과 함께 별도의 버그 목록을 얻을 수 있습니다.
만약 여러분이 Doxygen이 한 시간 이상 걸릴 정도로 큰 프로젝트를 가지고 있다면, 여러분은 그것을 여러 모듈로 나눌 수 있습니다. Doxygen은 나중에 태그 파일을 사용하여 함께 연결합니다.
예를 들어, 20개의 프로젝트가 포함된 대형 MSVC 솔루션이 있는 경우 디렉터리를 자체 Doxygen 실행으로 만든 다음 태그 파일을 사용하여 링커가 .libs를 결합하여 실행 파일을 만드는 것과 동일한 방식으로 출력을 결합할 수 있습니다.
링크 메타포를 더 문자 그대로 사용하여 각 Doxy 구성 파일이 .vcproj 파일에 해당하도록 하여 각 프로젝트(예: .lib 또는 .dll)가 자체 Doxy 출력을 얻을 수도 있습니다.
저는 하위 버전 사후 커밋 후크를 사용하여 변경된 디렉터리를 꺼내어 파일에 쓰고 매일 밤 웹 서버에서 doxygen html을 자동으로 다시 생성하여 항상 최신 문서를 유지합니다.
문서화하려는 모든 프로젝트에는 프로젝트별 설정과 기본 doxygen 설정에 포함된 작은 project.doxy 파일이 있습니다. 예:
PROJECT_NAME = "AlertServer"
PROJECT_NUMBER = 8.1.2
INPUT = "C:/Dev/src/8.1.2/Common/AlertServer"
HTML_OUTPUT = "AlertServer"
@INCLUDE = "c:\dev\CommonConfig.doxy"
윈도우즈 SVN 서버의 경우 후크를 사용합니다.
@echo off
for /F "eol=¬ delims=¬" %%A in ('svnlook dirs-changed %1 -r %2') do echo %%A >> c:\svn_exports\export.txt
매일 밤 실행합니다.
@echo off
rem ---------------
rem remove duplicates.
type nul> %TEMP%.\TEMP.txt
for /F "eol=¬ delims=¬" %%a in (c:\svn_exports\export.txt) do (
findstr /L /C:"%%a" < %TEMP%.\TEMP.txt > nul
if errorlevel=1 echo %%a>> %TEMP%.\TEMP.txt
)
copy /y %TEMP%.\TEMP.txt export_uniq.cmd >nul
if exist %TEMP%.\TEMP.txt del %TEMP%.\TEMP.txt
rem ---------------
rem fetch all the recently changed directories into the svn_exports directory
for /F "eol=¬ delims=¬" %%A in (c:\svn_exports\export_uniq.cmd) do (
svn export "file:///d:/repos/MyRepo/%%A" "c:/svn_exports/%%A" --force
)
rem ---------------
rem search through all dirs for any config files, if found run doxygen
for /R c:\svn_exports %%i in (*.doxy) do c:\tools\doxygen\bin\doxygen.exe "%i"
rem ---------------
rem now remove the directories to be generated.
del /F c:\svn_exports
이렇게 하면 중복 항목이 제거되고 .doxy 프로젝트 파일이 있는 모든 프로젝트가 검색되고 해당 프로젝트에서 doxygen이 실행됩니다.Voila: 웹 서버에서 완전히 문서화된 항상 최신 코드입니다.
복잡한 프로젝트의 경우 그룹 및 하위 그룹을 제어하는 모듈 관리용으로 별도의 파일을 두는 것이 유용할 수 있습니다.전체 계층을 한 곳에 배치한 다음 각 파일을 하위 그룹에 간단히 채울 수 있습니다. 예:
/**
* @defgroup example Top Level Example Group
* @brief The Example module.
*
* @{
*/
/**
* @defgroup example_child1 First Child of Example
* @brief 1st of 2 example children.
*/
/**
* @defgroup example_child2 Second Child of Example
* @brief 2nd of 2 example children.
*/
// @}
다른 그룹의 {} 내에 그룹의 정의를 포함하기만 하면 해당 그룹의 하위 그룹이 됩니다.그런 다음 코드 및 헤더 파일에서 함수는 그룹의 일부로 태그를 지정할 수 있으며 완료된 문서에서만 작동합니다.리팩터 코드와 일치하도록 설명서를 리팩터링하는 것이 훨씬 쉽습니다.
많은 링크를 사용합니다.링크(\see 또는 @see if you want)를 참조하고 올바른 클래스 이름을 사용하여 문서에서 다른 클래스 이름에 대한 참조를 사용하는지 확인합니다.예를 들어 클래스 FUZZ를 참조하는 경우오브젝트를 "오브젝트"로 지정한 후 바로 뒤에 클래스 이름을 씁니다(예: "오브젝트를 flazz(FUZZ)).대상)".
문서를 자동으로 작성하고 게시합니다.설명서를 자동으로 작성하는 과정에서 경고에 주의를 기울이면 잘못된 구조의 산소 주석을 매우 쉽게 작성할 수 있습니다.
가능한 한 많이 사용하세요.API 요소를 예제 코드에 자동으로 연결합니다.
@author 또는 @date(@date는 다른 게시물에서 언급되었습니다)를 신경 쓰지 마십시오.이 두 가지는 모두 수정 제어 시스템에 의해 처리됩니다.
항상 클래스에 설명을 포함합니다.클래스가 어떻게 사용되는지 또는 클래스가 사용되는 이유를 단순히 이름만 반영하는 것이 아니라 설명해 보십시오.
\defgroup을 사용하여 구성원 함수와 필드를 그룹화합니다.이것은 당신이 많은 말을 하지 않더라도 매우 도움이 됩니다.
일부 팀 구성원이 문서화하는 것을 피하거나 최소한의 문서 세트만 사용하기를 원하는 경우, Doxygen 구성에서 이러한 구성원을 사용 가능으로 설정할 수 있습니다.
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
doxygen 빌드 프로세스의 일부로 경고를 파일에 저장하고 경고 수를 최대한 낮게 유지합니다(적절한 경우 0).이렇게 하면 모든 공용 및 보호된 클래스 구성원은 각 함수 인수에 대해 @brief, @param 및 @return 이상이 필요합니다.이것은 대부분의 API를 설명하기에 충분하고 다른 살아있는 코드베이스를 방해하기에는 너무 많지 않습니다.
물론 최소 프로젝트 기준을 충족하는 한 사례별로 필요하다고 생각되는 만큼 문서화하도록 권장해야 합니다.하지만 최소값을 너무 높게 설정하지 마십시오. 그러면 결국 유용한 설명서를 얻지 못할 수 있습니다.
예를 들어, 우리 프로젝트에서는 다른 코더가 만질 수 있는 모든 것을 문서화해야 합니다.경고를 활성화하면 목표에 얼마나 근접했는지 확인할 수 있습니다.또한 @internal을 사용하여 일부 개인 회원과 함께 하는 작업을 설명하려고 합니다.
구성 지침 INLINE_SOURCES가 설명서에 너무 많은 코드를 입력하는 경우 \snipet 명령을 사용하여 코드의 특정 부분을 수동으로 인용할 수 있습니다.
/**
* Requirment XYZ is implemented by the following code.
*
* \snippet file.c CODE_LABEL
*/
int D()
{
//[CODE_LABEL]
if( A )
{
B= C();
}
//[CODE_LABEL]
}
참고: snipet은 원본 경로가 있는 위치가 아닌 EXAMPLE_PATH에서 파일을 가져옵니다.EXPASE_PATH 디렉티브의 INPUT 디렉티브와 동일한 파일 및 경로 목록을 넣어야 합니다.
생성하는 데 5분 이상 걸리는 대규모 프로젝트의 경우 단일 파일에 대한 doxygen을 신속하게 생성하여 웹 브라우저에서 볼 수 있는 것이 유용하다는 것을 알게 되었습니다.
파일 외부의 모든 항목에 대한 참조는 확인되지 않지만 기본 형식이 정상인지 확인하는 것이 유용할 수 있습니다.
이 스크립트는 단일 파일을 가져와서 doxy 구성을 프로젝트하고 doxygen을 실행합니다. 저는 이것을 제 IDE에서 실행하도록 설정했습니다.
#!/usr/bin/env python3
"""
This script takes 2-3 args: [--browse] <Doxyfile> <sourcefile>
--browse will open the resulting docs in a web browser.
"""
import sys
import os
import subprocess
import tempfile
doxyfile, sourcefile = sys.argv[-2:]
tempfile = tempfile.NamedTemporaryFile(mode='w+b')
doxyfile_tmp = tempfile.name
tempfile.write(open(doxyfile, "r+b").read())
tempfile.write(b'\n\n')
tempfile.write(b'INPUT=' + os.fsencode(sourcefile) + b'\n')
tempfile.flush()
subprocess.call(("doxygen", doxyfile_tmp))
del tempfile
# Maybe handy, but also annoying as default.
if "--browse" in sys.argv:
import webbrowser
webbrowser.open("html/files.html")
언급URL : https://stackoverflow.com/questions/51667/best-tips-for-documenting-code-using-doxygen
'prosource' 카테고리의 다른 글
| 판다에서 두 개의 데이터 프레임 행을 연결합니다. (0) | 2023.05.13 |
|---|---|
| 활성 탭 변경에 대한 부트스트랩 3 jquery 이벤트 (0) | 2023.05.13 |
| 긴 ASP에서 IIS 요청 시간 초과입니다.NET 연산 (0) | 2023.05.13 |
| pgadmin을 사용하여 herku 데이터베이스에 연결 (0) | 2023.05.13 |
| Excel: 셀에서 모든 캐리지 리턴을 제거하려면 어떻게 해야 합니까? (0) | 2023.05.13 |