Objective-C 문서 생성기 : HeaderDoc 대 Doxygen 대 AppleDoc
직장을위한 문서 생성 솔루션을 구현해야하며 제목에 언급 된 세 가지로 범위를 좁혔습니다. 저는 이러한 솔루션을 공식적으로 비교하는 방법으로 정보를 거의 찾을 수 없었으며, 위의 하나 이상의 경험이있는 분들이 무게를 실을 수 있기를 바랍니다.
다음은 초기 패스에서 얻을 수 있었던 것입니다.
HeaderDoc 장점 : 애플의 기존 문서와 일치, 애플 문서 세트 제작과의 호환성
HeaderDoc 단점 : 동작을 수정하기 어렵고, 프로젝트가 활발히 진행되지 않고, 많은 사람들이이 프로젝트에서 전환했습니다 (정량화 할 수는 없지만 부족한 것이 있음을 의미 함) ).
Doxygen을 장점 : (라텍스 등 같은) 널리 사용 기반, 매우 사용자 정의, 대부분의 출력 유형의 적극적인 지원 커뮤니티 B / C
Doxygen을 단점 : 그것은 사과 문서와 일치 동작합니다 / 보이게하기 위해 작업을 소요, 사과 docsets과의 호환성은 간단하지 않다
AppleDoc Pros : Apple의 기존 문서와 일치하는 것처럼 보임,
Apple 문서 세트 제작과의 호환성, AppleDoc 단점 : typedef, 열거 형 및 함수에 대한 문서 문제, 활발하게 개발 중
이게 정확합니까? 우리가 원하는 솔루션은 다음과 같습니다.
- Apples Objective-C 클래스 참조로 일관된 모양과 느낌
- 옵션을 클릭하여 Xcode 내에서 문서 참조를 가져온 다음 문서에 링크하는 기능 (애플의 클래스와 동일)
- 범주, 확장 등의 스마트 처리 (애플 클래스의 사용자 정의 범주도 포함)
- 자체 참조 페이지를 생성하는 기능 (예 : 이미지를 포함 할 수있는로드 중… Apple의 UIViewController 클래스 참조가 링크 된 페이지에 링크되는 방법과 같이 생성 된 클래스 참조에서 원활하게 링크 가능).
- 빌드 스크립트에 통합 할 수있는 실행하기 쉬운 명령 줄 명령
- 매우 큰 코드베이스의 원활한 처리
위의 모든 정보를 바탕으로 위의 솔루션 중 어느 것이 다른 것보다 분명히 더 나은 것이 있습니까? 추가 할 제안이나 정보는 대단히 감사하겠습니다.
doxygen의 창시자이자 수석 개발자로서 저도 제 관점을 제공하겠습니다
(분명히 편견도 있습니다 ;-).
Apple 자체 문서 스타일의 100 % 충실한 복제본을 찾고 있다면 AppleDoc이 더 나은 선택입니다. doxygen을 사용하면 똑같은 모습을 얻기가 어려울 수 있으므로 시도하지 않는 것이 좋습니다.
Xcode 문서 세트와 관련하여; Apple은 doxygen (Xcode 3이 출시되었을 때 작성 됨)으로 설정하는 방법에 대한 지침을 제공합니다 . Xcode 4의 경우 doxygen을 통합하는 방법에 대한 멋진 가이드 도 있습니다 .
버전 1.8.0부터 doxygen은 Markdown 마크 업과 많은 추가 마크 업 명령을 지원합니다.
doxygen을 사용하면 기본 페이지 (@mainpage)와 하위 페이지 (@subpage 또는 @page 사용)에 문서를 포함 할 수 있습니다. 페이지 내에서 섹션과 하위 섹션을 만들 수 있습니다. 사실, doxygen의 사용 설명서는 완전히 doxygen을 사용하여 작성되었습니다. 그 외에도 클래스 또는 함수를 함께 그룹화 (@defgroup 및 @ingroup 사용)하고 클래스 내부에서 사용자 지정 섹션을 만들 수 있습니다 (@name 사용).
Doxygen은 구성 파일을 입력으로 사용합니다. 기본값으로 템플릿을 생성 doxygen -g하거나 그래픽 편집기 를 사용 하여 템플릿 을 만들고 편집 할 수 있습니다. 다음을 사용하여 스크립트를 통해 doxygen을 통해 옵션을 파이프 할 수도 있습니다 doxygen -( 예 는 FAQ 의 질문 17 참조 ).
Doxygen은 Objective-C에 국한되지 않고 C, C ++ 및 Java를 포함한 광범위한 언어를 지원합니다. Doxygen은 또한 Mac 플랫폼에만 국한되지 않습니다. 예를 들어 Windows와 Linux에서도 실행됩니다. Doxygen의 출력은 HTML 이상을 지원합니다. PDF 출력 (LaTeX를 통해) 또는 RTF 및 매뉴얼 페이지를 생성 할 수 있습니다.
Doxygen은 또한 순수한 문서를 뛰어 넘습니다. doxygen은 소스 코드에서 다양한 그래프와 다이어그램을 만들 수 있습니다 ( 점 관련 옵션 참조 ). Doxygen은 또한 탐색 가능하고 구문 강조 표시된 코드 버전을 만들고 문서와 상호 참조 할 수 있습니다 ( 소스 브라우저 관련 옵션 참조).
Doxygen은 중소 규모 프로젝트의 경우 매우 빠릅니다 (다이어그램 생성이 느릴 수 있지만 요즘에는 여러 CPU 코어에서 병렬로 실행되고 한 실행의 그래프가 다음 실행에서 재 사용됨). 매우 큰 프로젝트 (예 : 수백만 줄의 코드)의 경우 doxygen을 사용하면 프로젝트를 여러 부분으로 분할 한 다음 여기에서 설명한대로 부분을 함께 연결할 수 있습니다 .
Objective-C에 doxygen을 사용하는 실제 사례는 여기 에서 찾을 수 있습니다 .
doxygen의 개발은 사용자 피드백에 크게 의존합니다. 질문과 토론을위한 활성 메일 링리스트 와 버그 및 기능 요청 모두에 대한 버그 추적기 가 있습니다.
대부분의 doxygen 사용자는 C 및 C ++ 코드에이를 사용하므로 당연히 이러한 언어는 가장 성숙한 지원을 제공하며 출력은 이러한 언어의 기능과 요구 사항에 맞게 조정됩니다. 즉, 다른 언어에 대한 희망과 문제도 진지하게 받아들입니다.
거의 모든 doxygen 개발과 대부분의 테스트를 Mac에서 직접 수행합니다.
나는 appledoc의 저자 이므로이 답변은 편향 될 수 있습니다. :) 언급 된 모든 생성기를 시도했지만 (그리고 그 이상) 내가 원하는 결과가 없었기 때문에 좌절했습니다 (당신과 비슷한 목표).
귀하의 요점에 따르면 (나는 appledoc과 doxygen에 대해서만 언급하지만 headerdoc를 잘 기억하지 못합니다) :
일관된 모양 : appledoc을 즉시 사용할 수 있고 CSS를 조정할 필요가 있지만 가능할 수도 있습니다.
문서 세트 생성 (Xcode 참조 용) : 검색 및 옵션 클릭 가능한 문서에 대한 appledoc 전체 지원, doxygen은 사용자가 직접 호출하는 데 필요한 xml 및 makefile을 생성합니다. 또한 appledoc은 게시 된 문서 세트를 즉시 지원합니다 .
카테고리 : appledoc을 사용하면 카테고리 를 알려진 클래스 에 병합 하거나 별도로 남겨 둘 수 있습니다. 기초 및 기타 애플 클래스 카테고리는 색인 파일 에 별도로 나열 됩니다 . doxygen : 시도했을 때 가장 잘 작동하지 않았습니다.
사용자 정의 참조 페이지 : appledoc 은 markdown 또는 사용자 정의 html을 사용하여 즉시 지원 합니다. doxygen : 기본 페이지에 사용자 정의 문서를 포함 할 수 있지만 더 많은 페이지를 포함 할 수 있는지 모르겠습니다.
쉬운 명령 줄 : 보는 방식에 따라 다릅니다. appledoc은 명령 줄 스위치를 통해 모든 인수를 가져올 수 있으므로 (선택 사항 인 전역 및 프로젝트 설정 plist 파일도 지원) 빌드 스크립트와 통합하기가 매우 쉽습니다. doxygen은 모든 매개 변수를 설정하기 위해 구성 파일을 사용해야합니다.
대규모 코드베이스 : 시간적으로 비교하지는 않았지만 모든 도구가이를 지원해야합니다. 또한 어떤 도구가 캐시 된 값을 지원하는지 확실하지 않습니다 (시간 절약을 위해 이전에 수집 된 데이터에 대해 실행 됨). 다음 주요 릴리스에이를 추가하려고합니다.
다른 도구를 사용해 본 지 얼마되지 않았으므로 위에서 언급 한 doxygen / headerdoc 문제가 해결되었을 수 있습니다! appledoc 자체에도 단점이 있습니다. 열거 형, 구조체, 함수 등에 대한 지원이 없다고 언급했듯이 (이 방향으로 수행 된 작업이 있었으므로이 포크를 확인하십시오 ), 사용을 방해 할 수있는 자체 문제 가 있습니다. 귀하의 요구 사항.
저는 현재 enums, structs 등에 대한 지원을 포함하여 대부분의 눈에 띄는 문제 를 다루는 주요 업데이트를 작업하고 있습니다 . 저는 더 큰 덩어리를 끝내고 충분히 안정적으로 만드는 즉시 새로운 것을 실험적인 브랜치에 정기적으로 푸시하고 있습니다. 진행. 그러나 아직은 매우 이르고 진행 상황은 내 시간에 따라 다르기 때문에 작업 솔루션까지 꽤 시간이 걸릴 수 있습니다.
Xcode 5는 이제 주석을 구문 분석하여 문서를 검색하고 표시합니다.
더 이상 appledoc 또는 doxygen을 사용할 필요가 없습니다 (적어도 문서를 내보내고 싶지 않은 경우). 자세한 정보는 여기 에서 찾을 수 있습니다 .
'IT TIP' 카테고리의 다른 글
| 문자열 변수의 N 번째 단어 (0) | 2020.10.20 |
|---|---|
| iPhone 중지 performSelector 취소 방법 (0) | 2020.10.20 |
| 사전을 사용하여 matplotlib를 사용하여 막대 플로팅 (0) | 2020.10.20 |
| Docker-이미지에서 호스트로 파일을 복사하려면 어떻게해야합니까? (0) | 2020.10.20 |
| Jenkins 작업 영역을 정리하는 방법이 있습니까? (0) | 2020.10.20 |