H 또는 CPP 파일에서 내부 라이브러리에 대한 doxygen 주석 블록을 어디에 둘?

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

---

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

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

장점 :

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

단점 :

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

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

---

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

클래스 주석은 클래스, 메서드

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

---

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

헤더 파일에 메소드에 대한 설명을 작성하고 모든 변수를 문서화합니다. 그 매개 변수는 자체의 구현보다 변경 될 가능성이 적으며 변경된 경우 함수를 변경해야합니다. .

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

예를 들면 :

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 모듈간에 분할 될 수 있습니다. 모든 공개 함수와 메소드가 보장되는 유일한 장소이기 때문에 문서를 헤더 파일에 넣는 것이 더 깔끔해 보입니다.

참고 URL : https://stackoverflow.com/questions/355619/where-to-put-the-doxygen-comment-blocks-for-an-internal-library-in-h-or-in-cpp