autogsdoc - GNUstep API 문서 생성기 및 XML->HTML 변환기
autogsdoc [-Files filename] [-GenerateHtml YES|no] [-Clean yes|NO] [-CleanTemplates yes|NO] [-IgnoreDependencies yes|NO] [-MakeDependencies yes|NO] [-ShowDependencies yes|NO] [-HeaderDirectory path] [-DocumentationDirectory path] [-Declared location] [-Project title] [-Standards yes|NO] [-DocumentAllInstanceVariables yes|NO] [-DocumentInstanceVariables YES|no] [-InstanceVariablesAtEnd yes|NO] [-ConstantsTemplate filename] [-FunctionsTemplate filename] [-MacrosTemplate filename] [-TypedefsTemplate filename] [-VariablesTemplate filename] [-SystemProjects string] [-LocalProjects string] [-Projects dictString] [-Verbose yes|NO] [-Warn yes|NO] [-WordMap dictString] [files]
autogsdoc 도구는 개발자가 GNUstep API에 대한 참조 문서를 생성하는 데 도움이 되는 명령줄 유틸리티입니다. 또한 개발자가 XML로 다른 문서를 작성 및 유지하고 HTML로 변환할 수 있습니다. 세부적으로 autogsdoc은 다음을 수행합니다.
Objective C 소스 코드(헤더 파일 및 선택적 소스 파일)에서 GSDoc XML 파일로 클래스, 범주, 프로토콜, 함수 및 매크로의 공용 인터페이스를 설명하는 특수 주석을 추출합니다.
소스 코드에서 생성되었거나 개발자가 수동으로 작성한 GSDoc XML 파일을 HTML로 변환합니다.
GSDoc XML 파일 세트를 기반으로 색인을 구성하고 이를 HTML로도 변환합니다.
가장 일반적인 사용법은 하나 이상의 헤더 파일 이름을 인수로 사용하여 명령을 실행하는 것입니다. 도구는 헤더와 동일한 디렉토리(또는 현재 디렉토리 또는 DocumentationDirectory를 사용하여 지정된 디렉토리)에서 해당 소스 파일을 자동으로 구문 분석합니다. 기본값) GSDoc 및 HTML 파일을 출력으로 생성합니다. 최상의 결과를 얻으려면 이 모드를 소스 파일이 포함된 디렉토리에서 실행해야 합니다. (C는 Objective C의 하위 집합이므로 이 도구는 일반 C 소스에서 함수 및 기타 C 구조를 문서화하도록 작동할 수 있습니다.)
GSDoc 파일은 추가로 직접 제공되거나 자체적으로 제공될 수 있으며 HTML로 변환됩니다. GSDoc 형식에 대한 자세한 내용은 GSDoc HTML 문서 또는 gsdoc(7) 매뉴얼 페이지를 참조하십시오.
마지막으로 HTML 파일은 명령줄에 제공될 수 있습니다. 그 안에 있는 코드 문서의 다른 부분에 대한 상호 참조는 현재 프로젝트에서 발견된 내용을 기반으로 다시 작성됩니다.
소스 코드 파서는 소스 파일에 있는 클래스의 메서드를 나열하는 GSDoc 문서를 자동으로 생성하고 소스 파일에서 특별히 형식이 지정된 주석의 텍스트를 포함합니다.
일반 슬래시와 단일 별표가 아닌 슬래시와 두 개의 별표로 시작하는 모든 주석은 GSDoc 마크업으로 간주되어 뒤에 오는 클래스 또는 메소드에 대한 설명으로 사용됩니다. 이 주석 텍스트는 형식이 다시 지정된 다음 출력에 삽입됩니다.
여러 주석이 동일한 항목과 연결되어 있는 경우 필요한 경우 각각 사이에 줄 바꿈(
)을 사용하여 결합됩니다.이 도구는 프로그램의 main() 함수를 포함하는 소스 파일의 이름을 제공하기만 하면 라이브러리뿐만 아니라 프로그램을 문서화하는 데 쉽게 사용할 수 있습니다. 문서의 첫 번째 장 끝에 있는 섹션(필요한 경우 첫 번째 장을 만듭니다).
옵션은 아래의 인수 및 기본값 섹션에 설명되어 있습니다.
특별한 추가 처리가 수행되는 경우가 있는데, 주로 소스 파일에서 발견된 첫 번째 주석에서 GSDoc 마크업의 다양한 청크가 추출되어 출력 문서의 적절한 위치에 배치될 수 있습니다.
AutogsdocSource:가 있는 줄에서 나머지 줄은 처리된 각 .h 파일이 동일한 .m 파일을 사용한다고 가정하는 대신 사용할 소스 파일 이름으로 간주됩니다. 이름. 헤더 파일이 여러 소스 파일에 정의된 항목을 선언하는 여러 AutogsdocSource: 행을 제공할 수 있습니다. 파일 이름이 절대적이면 제공된 그대로 사용됩니다. 반면 상대 경로인 경우 소프트웨어는 먼저 헤더 파일의 위치에 상대적인 소스 파일을 찾고, 거기에 없으면 autogsdoc가 실행 중인 현재 디렉터리에 상대적인 소스 파일을 찾고 마지막으로 DocumentationDirectory 기본값으로 지정된 디렉토리.
GSDoc 출력의 헤드에 있는 문서 내용의 요약입니다.
코드 작성자에 대한 설명 - 문서 작성자가 여러 명인 경우를 처리하기 위해 반복될 수 있습니다. GSDoc 출력의 헤드에 배치됩니다. 소스의 가독성을 돕기 위해 문서 작성자와 관련된 몇 가지 특별한 추가 처리가 수행됩니다.
이름 <이메일 주소>' 또는
이름 <이메일 주소>' 또는
이름' 또는
이름'이 인식되고 저자 요소로 변환되며, 이메일 요소를 포함할 수 있습니다.
부록, 색인 등에 사용하기 위한 문서 본문의 끝 바로 전에 GSDoc 출력에 배치됩니다.
생성된 클래스 문서 바로 앞에 배치됩니다. 문서화되는 코드의 작동 방식에 대한 전반적인 설명을 제공하는 데 사용됩니다. 프로그램의 main() 함수에 대한 모든 문서는 이 장의 끝에 섹션으로 삽입됩니다.
문서 내용의 저작권은 ... GSDoc 출력의 헤드에 있습니다. 소스의 가독성을 돕기 위해 몇 가지 특별한 추가 처리가 수행됩니다. '저작권(C) 텍스트' 형식의 모든 줄이 인식되고 복사 요소로 변환됩니다.
문서 개정 날짜 ... GSDoc 출력의 헤드에 배치됩니다. 이것이 생략되면 도구는 RCS 날짜 태그(사용 가능한 경우)에서 값을 생성하려고 시도합니다.
문서의 본문 시작 부분에 삽입 ... 소개 또는 목차 페이지 등을 제공하기 위한 것입니다.
문서 제목 ... GSDoc 출력의 헤드에 배치됩니다. 이것이 생략되면 도구는 자체의 (아마도 좋지 않은) 제목을 생성하므로 이 마크업을 수동으로 포함해야 합니다.
GSDoc 출력의 헤드에 있는 문서의 버전 식별자입니다. 이것이 생략되면 도구는 RCS Revision 태그(사용 가능한 경우)에서 값을 생성하려고 시도합니다.
NB 방금 설명한 마크업은 클래스, 카테고리 또는 프로토콜 문서 내에서 사용될 수 있습니다. 그렇다면 추출되어 클래스의 챕터인 클래스에 대한 나머지 문서로 둘러싸입니다. 나머지 클래스 문서는 일반적으로 장의 끝에 삽입되지만 대신
메서드 설명에 대한 텍스트를 제공하는 데 사용되는 주석에서 다음 마크업이 텍스트에서 제거되고 특별히 처리됩니다.
메서드는 클래스에 대해 지정된 초기화 프로그램으로 표시됩니다.
메서드는 하위 클래스가 재정의해야 하는 것으로 표시됩니다(예: 추상 메서드).
메소드는 하위 클래스가 재정의 하면 안 되는 것으로 표시됩니다.
마크업이 설명에서 제거되고 GSDoc 출력에서 마크업 뒤에 배치되어 메서드가 지정된 표준을 준수하는(또는 준수하지 않는) 것으로 설명됩니다.
일반적으로 주석의 텍스트는 표준화하고 멋지게 들여쓰기하기 위해 재형식화됩니다. 재형식화는
YES, NO 및 nil과 같이 잘 알려진 특정 상수는 ... 마크업으로 묶여 있습니다.
메서드 설명 내의 메서드 인수 이름은 ... 마크업으로 묶입니다.
메서드 이름(더하기 또는 빼기로 시작)은
클래스 이름(대괄호로 시작하고 끝나는)을 포함한 메서드 지정자는
'main()' 이외의 함수 이름('()'으로 끝남)은
이 도구는 특정 사용자 기본값을 허용합니다(물론 -Clean YES에서와 같이 기본 이름 앞에 '-'를 추가하고 나중에 값을 지정하여 명령줄 인수로 제공할 수 있음).
이 부울 값이 YES로 설정되면 도구는 문서를 생성하는 대신 프로젝트에서 생성된 모든 GSDoc 파일과 프로젝트에서 생성된 모든 html 파일(명시적으로 나열된 GSDoc 파일에서 생성된 모든 파일 포함)을 제거합니다. 마지막으로 프로젝트 색인 파일을 제거합니다. 이에 대한 유일한 예외는 CleanTemplates 플래그가 설정되지 않는 한 템플릿 GSDoc 파일(예: "-ConstantsTemplate ...", "-FunctionsTemplate ..." 인수 등을 사용하여 지정된 파일)이 삭제되지 않는다는 것입니다.
이 플래그는 정리 옵션이 지정된 경우 템플릿 GSDoc 파일을 다른 파일과 함께 제거할지 여부를 지정합니다. 기본값은 템플릿을 제거하지 않는 것입니다. 이러한 템플릿은 수동으로 생성되어 데이터가 삽입되었을 수 있기 때문입니다.
프로젝트의 모든 파일에서 상수에 대한 문서를 삽입해야 하는 템플릿 문서의 이름을 지정합니다. 이는 소스 코드의 상수가 여러 파일에 흩어져 있고 한 곳으로 그룹화해야 하는 경우에 유용합니다. 기본 템플릿 문서(개별 상수 문서가 삽입되는)에 원하는 다른 모든 정보가 포함되어 있는지 확인하는 것은 사용자의 책임이지만 편의상 autogsdoc는 파일이 필요한 경우 사용자를 위해 간단한 템플릿(다음에 편집할 수 있음)을 생성합니다. 존재하지 않습니다. 삽입은 템플릿의 back 요소 바로 앞(또는 없는 경우 body 요소의 끝 바로 앞)에서 이루어집니다.
헤더를 찾은 것으로 문서화할 위치를 지정합니다. 설명서에서 생성된 실제 이름은 헤더 파일 이름의 마지막 구성 요소를 이 기본값 값에 추가하여 구성됩니다. 이 기본값을 지정하지 않으면 HeaderDirectory 기본값이 앞에 붙은 헤더 파일의 전체 이름(명령줄에 제공된 대로)이 사용됩니다. GNUstep 기본 라이브러리에 대한 문서를 생성할 때 일반적인 용도는 '"-Declared Foundation"'입니다. 이로 인해 NSString이 'Foundation/NSString.h'에 선언되었다는 문서가 표시됩니다.
이 플래그를 사용하면 모든 인스턴스 변수에 대한 문서를 생성할 수 있습니다. 일반적으로 명시적으로 'public' 또는 'protected'로 선언된 항목만 문서화됩니다.
이 플래그를 사용하면 인스턴스 변수에 대한 문서를 완전히 끌 수 있습니다. 일반적으로 명시적으로 선언된 'public' 또는 'protected' 인스턴스 변수는 문서화됩니다.
이 플래그가 설정되면 HTML 생성기가 인스턴스 변수 문서를 클래스의 시작 부분이 아닌 끝에 배치하도록 지시합니다. 이것은 클래스의 일반 사용자에게 부차적인 관심만 있는 보호된 인스턴스 변수를 많이 사용하는 경우에 유용합니다.
생성된 문서가 배치될 디렉토리를 지정하는 데 사용할 수 있습니다. 이것이 설정되지 않은 경우 출력은 현재 디렉터리에 배치됩니다. 이 디렉토리는 또한 소스 파일(헤더가 아님)을 찾기 위한 최후의 수단으로 사용되며, 더 중요한 것은 이 디렉토리가 명령줄. 이러한 파일에 대해 제공된 모든 경로 정보는 제거되며 자동 생성되지 않은 경우에도 'DocumentationDirectory'에서 검색됩니다.
속성 목록 배열 (name1,name2,...) 형식으로 파일 이름 목록을 포함하는 파일 이름을 지정합니다. 이것이 있으면 프로그램 인수 목록의 파일 이름은 무시되고 이 파일의 이름은 처리할 이름 목록으로 사용됩니다.
프로젝트의 모든 파일에서 함수에 대한 문서를 삽입해야 하는 템플릿 문서의 이름을 지정합니다. 이는 함수 소스 코드가 여러 파일에 흩어져 있고 한 곳으로 그룹화해야 하는 경우에 유용합니다. 기본 템플릿 문서(개별 기능 문서가 삽입된 문서)에 원하는 다른 모든 정보가 포함되어 있는지 확인하는 것은 사용자의 책임이지만 편의상 autogsdoc는 파일이 필요한 경우 사용자를 위해 간단한 템플릿(다음에 편집할 수 있음)을 생성합니다. 존재하지 않습니다. 삽입은 템플릿의 back 요소 바로 앞(또는 없는 경우 body 요소의 끝 바로 앞)에서 이루어집니다.
HTML 출력을 생성할지 여부를 지정하는 데 사용할 수 있습니다. 기본값은 예입니다.
헤더 파일을 검색할 디렉토리를 지정하는 데 사용할 수 있습니다. 제공되면 이 값이 상대 헤더 이름 앞에 추가되고, 그렇지 않으면 상대 헤더 이름이 현재 디렉터리를 기준으로 해석됩니다. 절대 경로로 지정된 헤더 파일은 이 기본값의 영향을 받지 않습니다.
프로그램이 파일 수정 시간을 무시하고 파일을 재생성하도록 지정하는 데 사용할 수 있는 부울 값입니다. 종속성 검사 자체를 관리할 것으로 예상되는 'make' 시스템과 함께 사용하도록 제공됩니다.
이 값은 최종 문서 출력에서 상호 참조 생성을 위해 로컬 외부 프로젝트를 인덱싱 시스템에 자동으로 포함하는 것을 제어하는 데 사용됩니다. '없음'으로 설정하면 로컬 프로젝트 참조가 수행되지 않고, 그렇지 않으면 '로컬' GNUstep 문서 디렉토리에서 확장자가 '.igsdoc'인 파일을 재귀적으로 검색하고 해당 파일의 인덱싱 정보가 사용됩니다. 이 문자열의 값은 상호 참조에서 파일 이름을 생성하는 데에도 사용됩니다. 빈 문자열인 경우 사용할 경로는 igsdoc 파일이 발견된 동일한 디렉터리에 있는 파일로 간주됩니다. 그렇지 않으면 색인에서 이름의 접두사로 사용됩니다. NB. 현재 문서화 중인 프로젝트와 이름이 같은 로컬 프로젝트는 이 메커니즘에 포함되지 않습니다. 이러한 프로젝트를 포함하려면 -Projects ...를 사용하여 명시적으로 수행해야 합니다.
프로젝트의 모든 파일에서 매크로에 대한 문서를 삽입해야 하는 템플릿 문서의 이름을 지정합니다. 이것은 매크로 코드가 많은 파일에 흩어져 있고 한 곳으로 그룹화해야 하는 경우에 유용합니다. 기본 템플릿 문서(개별 매크로 문서가 삽입되는)에 원하는 다른 모든 정보가 포함되어 있는지 확인하는 것은 사용자의 책임이지만 편의상 autogsdoc는 파일이 필요한 경우 사용자를 위해 간단한 템플릿(다음에 편집할 수 있음)을 생성합니다. 존재하지 않습니다. 삽입은 템플릿의 back 요소 바로 앞(또는 없는 경우 body 요소의 끝 바로 앞)에서 이루어집니다.
make에 대한 종속성 정보를 출력하는 데 사용할 파일 이름입니다. 이는 프로젝트 이름의 종속성으로 프로젝트에 대해 알려진 모든 헤더 및 소스 파일을 나열하는 형식을 취합니다('프로젝트' 참조).
이 프로젝트의 이름을 지정하는 데 사용할 수 있습니다. 다른 프로젝트가 이 프로젝트의 항목을 상호 참조할 수 있도록 정보를 제공하기 위해 문서의 일부로 생성된 색인 참조 파일의 이름을 결정합니다.
이 값은 색인에서 찾은 파일 이름을 매핑하는 데 사용되는 값과 함께 외부 프로젝트에서 사용하는 igsdoc 색인/참조 파일의 경로를 포함하는 사전으로 제공될 수 있습니다. 예를 들어 프로젝트 색인(igsdoc) 파일에 'Foo' 클래스가 'Foo' 파일에 있고 해당 프로젝트 색인과 연결된 경로가 '/usr/share/doc/proj'인 경우 html이 생성됩니다. 출력은 '/usr/share/doc/prj/Foo.html' 에 있는 클래스를 참조할 수 있습니다. 표준 PropertyList 형식(OS X의 XML 형식이 아님)을 사용하고 줄 구분 기호로 세미콜론을 사용하고 작은따옴표로 묶어서 명령줄에 사전을 제공할 수 있습니다.
프로그램이 다른 파일에 대한 종속성 때문에 재생성 중인 파일을 기록하도록 지정하는 데 사용할 수 있는 부울 값입니다.
프로그램이 표준 준수에 대한 정보를 문서에 삽입해야 하는지 여부를 지정하는 데 사용되는 부울 값입니다. 이것은 문서화되는 코드가 GNUstep의 일부이고 아마도 OpenStep 표준을 준수하거나 MacOS-X 호환 방법을 구현한다고 가정하므로 GNUstep 라이브러리 및 도구 자체를 문서화할 때만 사용해야 합니다.
이 값은 최종 문서 출력에서 상호 참조 생성을 위해 시스템 외부 프로젝트를 인덱싱 시스템에 자동으로 포함하는 것을 제어하는 데 사용됩니다. 'None'으로 설정하면 시스템 프로젝트 참조가 수행되지 않고, 그렇지 않으면 'System' GNUstep 문서 디렉토리에서 확장자가 '.igsdoc'인 파일을 재귀적으로 검색하고 해당 파일의 인덱싱 정보가 사용됩니다. 이 문자열의 값은 상호 참조에서 파일 이름을 생성하는 데에도 사용됩니다. 빈 문자열인 경우 사용할 경로는 igsdoc 파일이 발견된 동일한 디렉터리에 있는 파일로 간주됩니다. 그렇지 않으면 색인에서 이름의 접두사로 사용됩니다. NB. 현재 문서화 중인 프로젝트와 이름이 같은 시스템 프로젝트는 이 메커니즘에 포함되지 않습니다. 이러한 프로젝트를 포함하려면 -Projects ...를 사용하여 명시적으로 수행해야 합니다.
프로젝트의 모든 파일에서 typedef에 대한 문서를 삽입해야 하는 템플릿 문서의 이름을 지정합니다. 이것은 typedef 소스 코드가 여러 파일에 흩어져 있고 한 곳으로 그룹화해야 하는 경우에 유용합니다. 기본 템플릿 문서(개별 typedef 문서가 삽입된)에 원하는 다른 모든 정보가 포함되어 있는지 확인하는 것은 사용자의 책임이지만 편의상 autogsdoc는 파일이 필요한 경우 사용자를 위해 간단한 템플릿(다음에 편집할 수 있음)을 생성합니다. 존재하지 않습니다. 삽입은 템플릿의 back 요소 바로 앞(또는 없는 경우 body 요소의 끝 바로 앞)에서 이루어집니다.
생성된 GSDoc 문서에서 '업' 링크에 사용할 이름을 제공하는 데 사용되는 문자열입니다. 이것은 일반적으로 프로젝트 내용의 색인을 포함하는 파일의 이름이어야 합니다. 누락되거나 빈 문자열로 설정되면 문서에 'up' 링크가 제공되지 않습니다.
프로젝트의 모든 파일에서 변수에 대한 문서를 삽입해야 하는 템플릿 문서의 이름을 지정합니다. 이는 가변 소스 코드가 여러 파일에 흩어져 있고 한 곳으로 그룹화해야 하는 경우에 유용합니다. 기본 템플릿 문서(개별 변수 문서가 삽입되는)에 원하는 다른 모든 정보가 포함되어 있는지 확인하는 것은 사용자의 책임이지만 편의상 autogsdoc는 파일이 필요한 경우 사용자를 위해 간단한 템플릿(다음에 편집할 수 있음)을 생성합니다. 존재하지 않습니다. 삽입은 템플릿의 back 요소 바로 앞(또는 없는 경우 body 요소의 끝 바로 앞)에서 이루어집니다.
자세한 디버그/경고 출력을 생성할지 여부를 지정하는 데 사용되는 부울입니다.
표준 경고 출력(예: 문서화되지 않은 메서드 보고서)을 생성할지 여부를 지정하는 데 사용되는 부울입니다.
이 값은 소스 파일에서 찾은 식별자/키워드를 다른 단어로 매핑하는 데 사용되는 사전입니다. 일반적으로 이것을 사용할 필요는 없지만 C 전처리기 매크로를 사용하여 파서가 혼동되는 것을 피하는 것이 때때로 도움이 됩니다. 덜 혼란스러운 것으로 매크로를 효과적으로 재정의할 수 있습니다. 식별자를 매핑하는 값은 다음 중 하나여야 합니다. 다른 식별자, 빈 문자열 - 값이 무시됨, 두 개의 슬래시('//') - 줄의 나머지 부분이 무시됨. 표준 PropertyList 형식(OS X의 XML 형식이 아님)을 사용하고 줄 구분 기호로 세미콜론을 사용하고 작은따옴표로 묶어서 명령줄에 사전을 제공할 수 있습니다.
'위로' 기본값은 사용되는 다른 문서의 '위로' 링크로 사용해야 하는 문서의 이름을 지정하는 데 사용됩니다. 이 이름은 경로나 확장자를 포함하지 않아야 합니다. 일반적으로 이 기본값으로 참조되는 문서는 프로젝트 색인을 포함하는 뒤로 섹션이 있어야 하는 손으로 편집한 GSDoc 문서여야 합니다. 예를 들어
<?xml version="1.0"?>
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 1.0.3//EN"
"http://www.gnustep.org/gsdoc-1_0_3.xml">
<gsdoc base="index">
<head>
<title>My project reference</title>
<author name="my name"></author>
</head>
<body>
<chapter>
<heading>My project reference</heading>
</chapter>
<back>
<index scope="project" type="title" />
</back>
</body>
</gsdoc> Source: .h, .m, .c
GSDoc: .gsdoc
Index: .igsdoc
HTML: .html여러 GSDoc 요소가 아직 HTML로 제대로 렌더링되지 않습니다. 이들은
오류 메시지 및 경고는 파이프라인의 각 단계(최상위 제어, 소스 구문 분석, GSDoc 구문 분석 및 인덱싱)에서 발생할 수 있습니다.
gsdoc(7), GNUstep(7)
Autogsdoc은 소스->GSDoc 및 GSDoc->HTML 변환을 각각 수행하는 'autodoc' 및 'gsdoc'의 이전 도구 두 가지 기능을 결합했습니다. 이러한 이전 도구와 GSDoc 형식은 이전 GDML SGML 언어를 기반으로 GNUstep용으로 개발되었습니다.
이 매뉴얼 페이지는 gnustep-base 1.9.2(2004년 3월)에서 처음 등장했습니다.
autogsdoc는 Richard Frith-Macdonald rfm@gnu.org가 작성했습니다.
이 매뉴얼 페이지는 Adrian Robert arobert@cogsci.ucsd.edu가 추가했습니다.