PHP 문서 생성 도구 정보

1. phpDocumentor란 무엇인가요?

PHPDocumentor는 PHP로 작성된 도구로, 표준 주석이 포함된 PHP 프로그램의 경우 상호 참조, 인덱싱 및 기타 기능을 사용하여 API 문서를 빠르게 생성할 수 있습니다. 이전 버전은 phpdoc입니다. 1.3.0부터 이름이 phpDocumentor로 변경되었습니다. 새 버전에서는 php5 구문에 대한 지원이 추가되었습니다. 동시에 클라이언트 브라우저에서 작업하여 문서를 생성할 수 있습니다. PDF, HTML, CHM에는 여러 가지 형태가 있어 매우 편리합니다.

PHPDocumentor가 작동하면 지정된 디렉터리 아래의 PHP 소스 코드를 스캔하고, 키워드를 스캔하고, 분석해야 할 주석을 가로채고, 주석의 특수 태그를 분석하고, xml 파일을 생성합니다. 그리고 완료된 클래스 및 모듈 정보 분석을 기반으로 해당 인덱스를 설정하고 xml 파일을 생성한 후, 생성된 xml 파일에 대해 지정된 형식의 파일을 맞춤형 템플릿을 사용하여 출력합니다.

2. phpDocumentor 설치

pear 아래의 다른 모듈과 마찬가지로 phpDocumentor 설치도 자동 설치와 수동 설치로 나누어지는데요.

아. pear를 통해 자동 설치

pear install PhpDocumentor

입력b. 수동 설치

http://manual.phpdoc.org/에서 최신 버전의 PhpDocumentor(현재 1.4.2)를 다운로드하고 콘텐츠의 압축을 푸세요.

3． PhpDocumentor를 사용하여 문서를 생성하는 방법

a. 명령줄 방법

phpDocumentor가 있는 디렉터리에서

Php -h

를 입력하여 가져옵니다. 자세한 매개변수 표, 몇 가지 중요한 매개변수는 다음과 같습니다.

-f 분석할 파일 이름, 쉼표로 구분된 여러 파일

-d 분석할 디렉터리, 여러 디렉터리 쉼표로 구분 분할

-t 생성된 문서의 저장 경로

-o 출력 문서 형식, 구조는 출력 형식: 변환기 이름: 템플릿 디렉터리입니다.

예: phpdoc -o HTML:frames:earthli -f test.php -t docs

b. 웹 인터페이스 생성

새 phpdoc에서 명령 오프라인으로 문서를 생성하는 것 외에도 클라이언트 브라우저에서 문서를 생성할 수도 있습니다. 구체적인 방법은 먼저 PhpDocumentor의 내용을 Apache 디렉터리에 배치하여 브라우저를 통해 액세스할 수 있도록 하는 것입니다. 표시됩니다:

파일 버튼을 클릭하고 처리할 PHP 파일이나 폴더를 선택하세요. 이 인터페이스에서 무시할 파일을 지정하여 특정 파일의 처리를 무시할 수도 있습니다.

그런 다음 출력 버튼을 클릭하여 생성된 문서의 저장 경로와 형식을 선택하세요.

마지막으로 생성을 클릭하면 phpdocumentor가 자동으로 문서 생성을 시작하고 생성 진행 상황과 상태가 표시됩니다. 성공적으로 완료되면

총 문서 작성 시간: 1초

done

Operation Completed!!

가 표시됩니다. 생성된 문서를 볼 수 있습니다. PDF 형식인 경우 이름은 기본적으로 document.pdf로 지정됩니다.

c. phpdocumentor 사용해 보기

아래에서는 phpdocumentor를 사용하여 문서를 생성하는 방법을 보여주기 위해 pear의 phpunit2를 예로 들어 보겠습니다.

먼저 필요한 매개변수를 결정합니다:

-d

c:/program files/easyphp5/php/pear/phpunit2

-t

c:/program files/easyphp5/php/phpunit2doc

-o

html:frames:phpedit

위 매개변수에 따라 다음 명령을 결합합니다:

phpdoc -d "c:/program files/easyphp5/php/pear/phpunit2" -t "c:/program files /easyphp5/php/phpunit2doc" -o "html:frames:phpedit"

위 명령을 실행한 후 phpdocumentor는 소스 파일 구문 분석을 시작하고 작업 정보를 출력합니다.

명령이 완료되면 문서가 생성되었습니다. 우리가 지정한 대상 디렉터리를 입력하고 브라우저로 index.html을 열어 생성된 문서를 확인하세요. 문서 인터페이스는 프레임을 기준으로 세 부분으로 구분됩니다. 왼쪽 상단은 패키지 정보, 왼쪽 하단은 탐색 정보, 오른쪽은 세부 정보 표시 페이지입니다.

인덱스, 함수 목록, 클래스 목록, 파일 목록 및 하위 패키지. 위의 클래스 링크를 클릭하면 전체 패키지의 클래스 트리를 명확하게 볼 수 있습니다. 수업 중 하나를 클릭하면 수업 설명 페이지로 들어갑니다. 클래스 설명 페이지에는 주로

[설명: 저작권, 작성자, 클래스 계층 구조 등], [클래스 변수], [클래스 상수], [메서드], [상속 변수]가 포함됩니다. ] , [상속된 메소드 : 매우 유용한 기능]

어때요, 아주 상세하죠? chm을 생성하려면 이전 -o 매개변수를 "chm:default: default"로 변경하여 phpdocumentor가 chm 프로젝트 파일을 생성하도록 하면 Microsoft의 chm 도구로 컴파일하여 사용 가능한 chm 파일을 얻을 수 있습니다.

d. 중국어 왜곡 해결

댓글이 중국어인 경우 PhpDocumentor/phpDocumentor/Converters/*에 있는 해당 템플릿의 언어 태그를 iso-8859-1에서 다음으로 변환해야 합니다. utf-8 바꾸십시오. 그렇지 않으면 생성된 코드가 깨집니다.

4. PHP 코드에 표준 주석 추가

PHPDocument는 소스 코드의 주석에서 문서를 생성하므로 프로그램에 주석을 추가하는 과정은 문서를 컴파일하는 과정이기도 합니다. 이러한 관점에서 PHPdoc은 좋은 프로그래밍 습관을 기르고 사양과 일반 텍스트를 사용하여 프로그램에 주석을 달도록 권장합니다. 동시에 문서 준비와 문서 간의 동기화되지 않는 문제를 어느 정도 방지합니다. 이후 업데이트. phpdocumentor에서는 주석이 문서 주석과 문서가 아닌 주석으로 구분됩니다. 소위 문서 주석이란 특정 키워드 앞에 여러 줄로 된 주석을 말합니다. 특정 키워드는 class, var 등 phpdoc에서 분석할 수 있는 키워드를 말합니다. 자세한 내용은 부록 1을 참조하세요. 키워드 앞에 오지 않거나 표준화되지 않은 주석을 비문서 주석이라고 합니다. 이러한 주석은 phpdoc에서 분석되지 않으며 생성한 API 문서에 나타나지 않습니다.

문서 주석 작성 방법:

모든 문서 주석은 /**첫 번째 여러 줄 주석은 phpDocumentor에서 DocBlock이라고 합니다. DocBlock은 소프트웨어 개발자가 작성한 특정 키워드에 대한 도움말 정보를 참조하여 다른 사람들이 이 키워드의 구체적인 목적과 사용 방법을 알 수 있도록 합니다. PhpDocumentor에서는 DocBlock에 다음 정보가 포함된다고 규정합니다.

1. 기능 간략 설명 영역

2. 상세 설명 영역

3. 문서 설명 첫 번째 줄은 함수 설명 영역입니다. 텍스트는 일반적으로 이 클래스, 메서드 또는 함수의 기능을 간략하게 설명합니다. 함수 설명 텍스트는 생성된 문서의 인덱스 영역에 표시됩니다. 기능 설명 영역의 내용은 빈 줄이나 "."로 끝날 수 있습니다. 함수 설명 영역 뒤에는 자세한 설명 영역이 옵니다. 이 부분은 주로 API의 기능과 목적을 자세히 설명하며 가능한 경우 사용 예도 포함합니다. 이 섹션에서는 API 함수 또는 메소드의 일반적인 목적과 사용법을 명확히 하는 데 중점을 두고 플랫폼 관련 정보의 경우 일반 정보와 다르게 처리해야 합니다. 일반적인 접근 방식은 새 줄을 시작하고 특정 플랫폼에 대한 주의 사항이나 특별 정보를 작성하는 것입니다. 이 정보는 독자가 경계 조건, 매개 변수 범위, 중단점 등과 같은 해당 테스트 정보를 작성할 수 있을 만큼 충분해야 합니다. . 그 다음에는 빈 줄과 문서 태그가 있는데, 이는 주로 호출 매개변수 유형, 반환 값 및 유형, 상속 관계, 관련 메서드/함수 등과 같은 일부 기술 정보를 나타냅니다.

문서 태그에 대한 자세한 내용은 --문서 태그를 참조하세요. 와 같은 태그는 문서 주석에도 사용할 수 있습니다. 자세한 내용은 부록 2를 참조하세요.

다음은 문서 주석 예시

/**

* 두 개의 숫자 더하기를 구현한 함수 add

*

* 이 함수는 두 숫자 a와 b를 받아 그 합 c를 반환합니다.

*

* @param int addend

* @param int summand

* @return 정수

*/

함수 Add($a, $ b)로 구성됩니다.

{

return $a+$b;

}

생성된 문서는 다음과 같습니다.

추가

정수 더하기( int $a, int $b)

[line 45]

두 숫자의 더하기를 구현하는 함수 add

상수 간단한 덧셈 계산, 이 함수는 두 숫자 a와 b를 받아들이고 그 합을 반환합니다. c

매개변수

? int $a - 가수

? 추가예정

5. 문서 태그:

문서 태그의 사용 범위는 태그를 사용하여 수정할 수 있는 키워드 또는 기타 문서 태그를 의미합니다. 모든 문서 태그는 각 줄의 * 뒤에 @로 시작됩니다. @ 표시가 단락 중간에 나타나면 해당 표시는 일반 내용으로 간주되어 무시됩니다.

@access

사용 범위: class, function, var, 정의, 모듈

이 태그는 키워드의 액세스 권한을 나타내는 데 사용됩니다: private, public 또는 protected

@author

사용 범위: 클래스, 함수, var, 정의, 모듈, 사용

저작자 지정

@copyright

사용 범위: 클래스, 함수, var, 정의, 모듈, 사용

저작권 정보 표시

@deprecated

사용 범위: 클래스, 함수, var, 정의, 모듈, constent , global, include

사용되지 않거나 더 이상 사용되지 않는 키워드를 나타냅니다

@example

이 태그는 파일 콘텐츠를 구문 분석하고 강조 표시하는 데 사용됩니다. PHPDOC는 이 태그

@const

가 제공하는 파일 경로에서 파일 내용을 읽으려고 시도합니다. 사용 범위: 정의

는 PHP에서 정의의 상수를 지정하는 데 사용됩니다.

@final

사용 범위: 클래스, 함수, var

키워드가 final 클래스, 메서드, 속성임을 나타내며 파생 및 수정을 금지합니다.

@filesource

는 이 태그가 현재 구문 분석된 PHP 파일의 내용을 직접 읽고 표시한다는 점을 제외하면 예제와 유사합니다.

@global

이 함수에서 참조되는 전역 변수를 나타냅니다.

@ingore

는 문서에서 지정된 키워드를 무시하는 데 사용됩니다.

@license

는 html 태그의 와 동일합니다. 먼저 URL이고 그 다음에는 표시할 콘텐츠입니다.

예: Baidu

는 @license로 쓸 수 있습니다. http://www.baidu.com Baidu

@link

라이센스와 유사합니다

그러나 링크를 통해 문서의 모든 키워드를 가리킬 수도 있습니다

@name

키워드의 별칭을 지정합니다.

@package

사용 범위: 페이지 수준 정의, 함수, 포함

클래스 수준 클래스, var, 메서드

를 사용하여 논리적으로 적용 하나 또는 여러 개의 키워드가 함께 그룹화됩니다.

@abstrcut

현재 클래스가 추상 클래스임을 나타냅니다.

@param

함수의 매개변수를 나타냅니다

@ return

메서드나 함수의 반환 포인터를 나타냅니다.

@static

키워드가 정적임을 나타냅니다.

@var

변수 유형 지정

@version

버전 정보 지정

@todo

개선 또는 구현 부족 표시

@throws

이 함수가 발생할 수 있는 오류 예외와 극단적인 상황을 나타냅니다

위에서 언급한 것처럼 일반 문서 마크업 태그는 각 줄의 시작 부분에 @ 를 표시해야 합니다. 또한 인라인 태그라는 태그도 있으며 이는 다음을 포함하여 {@}로 표시됩니다. 🎜 >사용법은 @link와 동일

{@source}

함수나 메소드의 내용을 표시

6. 일부 댓글 사양

a. 댓글은

/**

* XXXXXXX

*/

형식이어야 합니다.b. 변수 함수는 glboal로 표시되어야 합니다.

c. 변수의 경우 해당 유형(int, string, bool...)을 var

d로 표시해야 합니다. 함수는 param 및 return을 통해 해당 매개변수와 반환 값을 표시해야 합니다. 마커

e. 두 번 이상 나타나는 키워드의 경우 ingor를 통해 중복된 키워드를 무시하고 하나만 유지하세요.

다른 함수나 클래스가 호출되는 경우 링크나 다른 태그를 사용하세요. 해당 섹션을 참조하여 문서를 쉽게 읽을 수 있도록 하세요.

g. 코드 가독성을 높이기 위해 필요한 경우 문서화되지 않은 주석을 사용하세요.

h. 가능하면 문장보다는 문구를 사용하여 설명 내용을 간결하고 명확하게 유지하세요.

i. 전역 변수, 정적 변수 및 상수는 해당 태그로 표시되어야 합니다.

7. 요약

문서 작성은 지루하지만 필요한 작업입니다. API 수준 문서는 반복되는 작업이 많고 일관성을 유지하는 데 어려움이 있음을 의미합니다. 여기 계신 모든 분들께 추천하고 싶은 것은 php5 구문 분석을 지원하는 문서 도구인 phpDocumentor입니다. phpDocumentor는 표준화된 주석을 작성하고 이해하기 쉽고 명확한 구조의 문서를 생성하는 데 도움이 되는 매우 강력한 자동 문서 생성 도구로, 코드 업그레이드, 유지 관리, 인계 등에 매우 유용합니다. phpDocumentor를 사용하면 코드에서 함수 및 메서드 정의를 자동으로 추출할 수 있을 뿐만 아니라 다양한 클래스 간의 관계를 자동으로 처리하고 그에 따라 클래스 트리를 생성할 수 있습니다. 문서를 html, chm 또는 pdf로 생성하도록 선택할 수도 있습니다. phpDocumentor를 사용하면 문서 작업이 훨씬 쉬워집니다. phpDocumentor에 대한 자세한 설명은 공식 웹사이트(http://manual.phpdoc.org/)에서 확인할 수 있습니다.