1. phpDocumentor란 무엇인가요?
PHPDocumentor는 PHP로 작성된 도구로, 표준 주석이 포함된 PHP 프로그램의 경우 상호 참조, 인덱싱 및 기타 기능을 사용하여 API 문서를 빠르게 생성할 수 있습니다. 이전 버전은 phpdoc입니다. 1.3.0부터 이름이 phpDocumentor로 변경되었습니다. 새 버전에서는 php5 구문에 대한 지원이 추가되었습니다. 동시에 클라이언트 브라우저에서 작업하여 문서를 생성할 수 있습니다. PDF, HTML, CHM에는 여러 가지 형태가 있어 매우 편리합니다.
PHPDocumentor가 작동하면 지정된 디렉터리 아래의 PHP 소스 코드를 스캔하고, 키워드를 스캔하고, 분석해야 할 주석을 가로채고, 주석의 특수 태그를 분석하고, xml 파일을 생성한 다음, 분석된 클래스 및 모듈 정보를 분석하고, 해당 인덱스를 설정하고, xml 파일을 생성하고, 생성된 xml 파일에 대해 지정된 형식의 파일을 사용자 정의 템플릿을 사용하여 출력합니다.
2. phpDocumentor 설치
pear의 다른 모듈과 마찬가지로 phpDocumentor 설치도 자동 설치와 수동 설치 두 가지 방법으로 나누어져 있습니다.
a. pear를 통해 자동 설치
명령줄에 입력
pear install PhpDocumentor
b. 수동 설치
http://manual.phpdoc.org/에서 최신 버전의 PhpDocumentor(현재 1.4.0)를 다운로드하고 콘텐츠의 압축을 푸세요.
3. PhpDocumentor를 사용하여 문서를 생성하는 방법
명령줄 방법:
phpDocumentor가 있는 디렉터리에서
Php –h
를 입력하여 자세한 매개 변수 목록을 가져옵니다. 그 중 몇 가지 중요한 매개 변수는 다음과 같습니다. :
-f 분석할 파일 이름, 여러 파일을 쉼표로 구분
-d 분석할 디렉터리, 여러 디렉터리를 쉼표로 구분
-t 생성된 문서의 저장 경로
-o 출력 문서 형식의 경우 구조는 출력 형식: 변환기 이름: 템플릿 디렉터리입니다.
예: phpdoc -o HTML:frames:earthli -f test.php -t docs
웹 인터페이스 생성
새 phpdoc에서는 명령줄에서 문서를 생성하는 것 외에도 다음을 생성할 수도 있습니다. 클라이언트의 문서 브라우저에서 문서를 생성하려면 먼저 PhpDocumentor의 내용을 Apache 디렉토리에 배치하여 브라우저를 통해 액세스할 수 있도록 하는 것입니다. 액세스 후 다음 인터페이스가 표시됩니다.
클릭 파일 버튼을 누르고 처리할 PHP 파일 폴더를 선택하면 이 인터페이스에서 무시할 파일을 지정하여 특정 파일의 처리를 무시할 수도 있습니다.
그런 다음 출력 버튼을 클릭하여 생성된 문서의 저장 경로와 형식을 선택합니다.
마지막으로 생성을 클릭하면 phpdocumentor가 자동으로 문서 생성을 시작하며 생성 진행 상황과 상태가 하단에 표시됩니다. 성공하면
총 문서화 시간: 1초
done
작업 완료!!
그러면 생성된 문서를 볼 수 있습니다. PDF 형식인 경우 이름은 기본적으로 다음과 같습니다. 문서.pdf.
4. PHP 코드에 표준화된 주석 추가
PHPDocument는 소스 코드의 주석에서 문서를 생성하므로 프로그램에 주석을 추가하는 과정은 문서를 컴파일하는 과정이기도 합니다.
이러한 관점에서 PHPdoc은 좋은 프로그래밍 습관을 기르고 사양과 명확한 텍스트를 사용하여 프로그램에 주석을 달도록 권장하는 동시에 나중에 문서 및 문서 업데이트의 비동기 개발을 어느 정도 방지합니다. 몇 가지 질문.
phpdocumentor에서는 댓글은 문서용 댓글과 비문서용 댓글로 구분됩니다.
일명 문서 주석은 특정 키워드 앞에 여러 줄로 된 주석입니다. 특정 키워드는 class, var 등 phpdoc에서 분석할 수 있는 키워드를 말합니다. 자세한 내용은 부록 1을 참조하세요.
키워드 앞에 오지 않거나 표준화되지 않은 댓글을 비문서 댓글이라고 합니다. 이러한 댓글은 phpdoc에서 분석되지 않으며 생성한 API 문서에 표시되지 않습니다.
3.2 문서 주석 작성 방법:
모든 문서 주석은 /**로 시작하는 여러 줄의 주석으로, phpDocumentor에서는 DocBlock이라고 합니다. 소프트웨어 개발자가 작성한 핵심 주석을 말합니다. 키워드의 사용을 통해 다른 사람들이 이 키워드의 구체적인 목적과 사용 방법을 알 수 있습니다. PhpDocumentor에서는 DocBlock에 다음 정보가 포함된다고 규정합니다.
1. 기능 간략 설명 영역
2. 상세 설명 영역
3. 태그 표시
문서 주석의 첫 번째 줄은 기능 설명 영역입니다. 텍스트는 일반적으로 이 클래스, 메소드 또는 함수의 기능을 간략하게 설명합니다. 간략한 기능 설명 텍스트는 생성된 문서의 색인 영역에 표시됩니다. 함수 설명 영역의 내용은 빈 줄로 끝날 수 있습니다.
함수 설명 영역이 빈 줄 다음으로 자세한 설명 영역이 옵니다. 이 부분은 주로 API의 기능과 목적을 설명하는 부분입니다. 자세한 내용은 가능하다면 사용법 등의 예를 제시할 수도 있습니다. 이 섹션에서는 API 함수 또는 메서드의 일반적인 목적과 사용법을 명확히 하는 데 중점을 두고, 플랫폼 관련 정보는 일반 정보와 다르게 처리해야 합니다. 일반적인 접근 방식은 새 줄을 시작한 다음 특정 플랫폼에 대한 주의 사항이나 특별 정보를 작성하는 것입니다. 이 정보는 독자가 경계 조건, 매개 변수 범위, 중단점 등과 같은 해당 테스트 정보를 작성할 수 있을 만큼 충분해야 합니다.
뒤에는 빈 줄이 있고 문서 태그가 있는데, 이는 주로 호출 매개변수 유형, 반환 값 및 유형, 상속 관계, 관련 메서드/함수 등 일부 기술 정보를 나타냅니다.
문서 태그에 대한 자세한 내용은 섹션 4: 문서 태그를 참조하세요.
문서 주석에 등의 태그를 사용할 수도 있습니다. 자세한 내용은 부록 2를 참조하세요.
다음은 문서 주석의 예입니다
/**
* add 함수, 두 숫자의 덧셈 구현
*
* 간단한 덧셈 계산, 이 함수는 두 숫자 a와 b를 받아들이고 그 합 c를 반환합니다.
*
* @ param int addend
* @param int addend
* @return 정수
*/
function Add($a, $b)
{
return $a $b; >}
생성된 문서는 다음과 같습니다.
Add
integer Add( int $a, int $b)
[line 45]
함수 add, 두 숫자의 추가를 구현합니다.
단순한 상수 덧셈 계산을 위해 함수는 두 숫자 a와 b를 받아들이고 그 합을 c로 반환합니다.
매개변수
• int $a - addend
• int $b - summand
5 . 문서 태그:
문서 태그의 사용 범위는 해당 태그를 사용하여 수정할 수 있는 키워드나 기타 문서 태그를 의미합니다.
모든 문서 태그는 각 줄의 * 뒤에 @로 시작됩니다. @ 표시가 단락 중간에 나타나면 해당 표시는 일반 내용으로 간주되어 무시됩니다.
@access
사용 범위: 클래스, 함수, var, 정의, 모듈
이 태그는 키워드의 액세스 권한을 나타내는 데 사용됩니다: private, public 또는 protected
@author
작성자
@copyright
사용 범위: 클래스, 함수, var, 정의, 모듈, 사용
저작권 정보 표시
@deprecated
사용 범위: 클래스, 함수, var, 정의, 모듈, constent , global, include
사용되지 않거나 더 이상 사용되지 않는 키워드를 나타냅니다.
@example
이 태그는 파일 콘텐츠를 구문 분석하고 강조 표시하는 데 사용됩니다. Phpdoc은
@const
범위 사용: 정의
PHP에서 정의의 상수를 나타내는 데 사용됩니다
@final
범위 사용 : class ,function,var
은 키워드가 최종 클래스, 메서드 또는 속성이며 파생 및 수정이 금지됨을 나타냅니다.
@filesource
이 태그가 현재 구문 분석된 PHP 파일의 내용을 직접 읽고 표시한다는 점을 제외하면 예제와 유사합니다.
@global
이 함수에서 참조되는 전역 변수를 나타냅니다.
@ingore
는 문서에서 지정된 키워드를 무시하는 데 사용됩니다.
@license
는 html 태그의 <와 동일합니다. ;a> 먼저 URL을 입력한 다음 표시할 콘텐츠를 입력하세요.
예를 들어 Baidu
는 다음과 같이 쓸 수 있습니다. @license http://www.baidu.com Baidu
@link
라이센스
와 유사하지만
@name
링크를 통해 문서의 모든 키워드를 가리킬 수도 있습니다. 키워드 지정 별명.
@package
사용 범위: 페이지 레벨 -> 정의, 함수, 포함
클래스 레벨 ->class, var, 메소드
는 하나 또는 여러 개의 키워드를 논리적으로 결합하는 데 사용됩니다. .
@abstrcut
현재 클래스가 추상 클래스임을 나타냅니다.
@param
함수의 매개변수를 지정합니다
@return
메서드나 함수의 반환 포인터를 지정합니다
@static
관전자가 정적임을 나타냅니다.
@var
변수 유형 표시
@version
버전 정보 표시
@todo
개선해야 할 부분이나 구현하지 말아야 할 부분 표시
@throws
다음을 표시 이 함수는 매우 드물게 오류 예외가 발생할 수 있습니다
위에서 언급한 것처럼 일반 문서 태그는 각 줄의 시작 부분에 @를 표시해야 합니다. 또한 {@} 표현식을 사용하는 인라인 태그라는 태그도 있습니다. 다음 유형:
{@link}
사용법은 @link와 동일
{@source}
함수 또는 메소드의 내용을 표시
6. 일부 주석 사양
a. 주석은
/**
* XXXXXXX
*/
형식이어야 합니다. b. 전역 변수를 참조하는 함수의 경우 glboal 태그를 사용해야 합니다.
c. 변수의 경우 해당 유형은 var(int, string, bool...)로 표시되어야 합니다.
d. 함수는 param 및 반환 마커를 통해 매개변수와 반환 값을 나타내야 합니다. 2회 발생 2회 이상 사용된 키워드의 경우 중복되는 것은 ingore를 통해 무시하고 하나만 유지해야 합니다
f. 다른 함수나 클래스가 호출되는 경우에는 link나 기타 태그를 사용하여 해당 부분으로 연결해야 합니다. 읽기의 문서화를 용이하게 합니다.
g. 코드 가독성을 높이기 위해 필요한 경우 문서화되지 않은 주석을 사용하세요.
h. 가능하면 문장보다는 문구를 사용하여 설명 내용을 간결하고 명확하게 유지하세요.
i. 전역변수, 정적변수, 상수는 해당 태그로 기술해야 합니다.
현재 페이지 1/2 12다음 페이지
이상으로 갈 문서를 소개했습니다. 1/2페이지에는 갈 문서의 내용이 포함되어 있어 PHP 튜토리얼에 관심이 있는 친구들에게 도움이 되기를 바랍니다.