H 또는 CPP 파일에서 내부 라이브러리에 대한 doxygen 주석 블록을 어디에 둘 것인가? [닫은]

상식적으로 Doxygen 주석 블록은 클래스, 구조체, 열거 형, 함수, 선언이있는 헤더 파일에 넣어야합니다. 나는 이것이 소스없이 배포되는 라이브러리에 대한 건전한 주장이라는 데 동의합니다 (객체 코드가있는 헤더와 라이브러리 만).

하지만 ... 저는 전체 소스 코드와 함께 사용될 회사 내부 (또는 나 자신을위한 부수 프로젝트) 라이브러리를 개발할 때 정반대의 접근 방식을 생각했습니다. 내가 제안하는 것은 헤더에 선언 된 클래스와 함수의 인터페이스를 어지럽히 지 않도록 구현 파일 (HPP, INL, CPP 등)에 큰 주석 블록을 넣는 것입니다.

장점 :

• 헤더 파일의 복잡함이 줄어들고 함수 분류 만 추가 할 수 있습니다.
• 예를 들어 Intellisense를 사용할 때 미리 볼 수있는 주석 블록은 충돌하지 않습니다. 이것은 .H 파일에 함수에 대한 주석 블록이 있고 동일한 .H 파일에 인라인 정의가있을 때 관찰 한 결함입니다. 그러나 .INL 파일에서 포함됩니다.

단점 :

• (분명한 것) 주석 블록은 선언이있는 헤더 파일에 없습니다.

그래서, 당신은 무엇을 생각하고 제안 할 수 있습니까?

사람들이 코드를 사용하고 작업 할 때 읽고 쓸 수있는 곳에 문서를 두십시오.

클래스 주석은 클래스 앞에, 메서드 주석은 메서드 앞에 있습니다.

이것이 유지 관리를 보장하는 가장 좋은 방법입니다. 그것은 또한 당신의 헤더 파일이 상대적으로 상체를 유지하고 피할 감동 헤더 더러운 트리거 재 구축 할 일으키는 방법 문서를 업데이트하는 사람의 문제를. 나는 실제로 사람들이 나중에 문서 작성을위한 변명으로 사용하는 것을 알고 있습니다 !

저는 이름이 여러 곳에 기록 될 수 있다는 사실을 활용하고 싶습니다.

헤더 파일에 메서드에 대한 간략한 설명을 작성하고 모든 매개 변수를 문서화합니다. 이러한 매개 변수는 메서드 자체의 구현보다 변경 될 가능성이 적으며 변경 될 경우 함수 프로토 타입을 어떤 경우에도 변경해야합니다. .

실제 구현 옆의 소스 파일에 긴 형식의 문서를 넣었으므로 메서드가 발전함에 따라 세부 사항을 변경할 수 있습니다.

예를 들면 :

mymodule.h

/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);

mymodule.cpp

/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
  return b + a;
}

헤더에 주석이 있다는 것은 주석이 변경된 경우 클래스의 모든 사용자를 다시 컴파일해야 함을 의미합니다. 대규모 프로젝트의 경우 코더는 다음 20 분 동안 모든 것을 재 구축하는 데 소비 할 위험이있는 경우 헤더의 주석을 업데이트하는 경향이 적습니다.

그리고 .. html 문서를 읽고 문서를위한 코드를 찾아 보지 않아야하므로 주석 블록이 소스 파일에서 찾기가 더 어렵다는 것은 큰 문제가 아닙니다.

헤더 : 파일을 볼 때 다른 "노이즈"가 적기 때문에 주석을 읽기가 더 쉽습니다.

출처 : 그러면 주석을 보면서 읽을 수있는 실제 기능이 있습니다.

헤더에 주석이 달린 모든 전역 함수와 소스에 주석이 달린 로컬 함수를 사용합니다. 원하는 경우 copydoc 명령을 포함하여 문서를 여러 번 작성하지 않고도 여러 위치에 삽입 할 수도 있습니다 (유지 관리에 더 좋음).

그러나 간단한 명령으로 결과를 다른 파일 문서로 복사 할 수도 있습니다. 예 :-

내 파일 1.h

/**
 * \brief Short about function
 *
 * More about function
 */
WORD my_fync1(BYTE*);

내 파일 1.c

/** \copydoc my_func1 */
WORD my_fync1(BYTE* data){/*code*/}

이제 두 기능에 대한 동일한 문서를 얻습니다.

이렇게하면 최종 출력의 여러 위치에 표시된 문서를 한 곳에서 작성하는 동시에 코드 파일의 노이즈를 줄일 수 있습니다.

일반적으로 인터페이스 문서 (\ param, \ return)를 .h 파일에, 구현 문서 (\ details)를 .c / .cpp / .m 파일에 넣습니다. Doxygen은 기능 / 방법 문서의 모든 것을 그룹화합니다.

헤더 파일에 모든 것을 넣었습니다.

나는 모든 것을 문서화하지만 일반적으로 공개 인터페이스 만 추출합니다.

프로그래밍을 위해 QtCreator를 사용하고 있습니다. 매우 유용한 트릭은 헤더 파일에서 선언을 가져 오기 위해 함수 또는 메서드를 Ctrl- 클릭하는 것입니다.

메소드가 헤더 파일에 주석 처리되면 찾고있는 정보를 빠르게 찾을 수 있습니다. 그래서 저에게는 주석이 헤더 파일에 있어야합니다!

C ++에서는 때때로 구현이 헤더와 .cpp 모듈간에 분할 될 수 있습니다. 모든 공개 함수와 메소드가 보장되는 유일한 장소이기 때문에 문서를 헤더 파일에 넣는 것이 더 깔끔해 보입니다.