PHPDocumentor는 PHP로 작성된 도구로, 표준 주석이 포함된 PHP 프로그램의 경우 상호 참조, 인덱싱 및 기타 기능을 사용하여 API 문서를 빠르게 생성할 수 있습니다. 이전 버전은 phpdoc입니다.
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를 통해 자동으로 설치하고 명령줄에 입력
배 설치 PhpDocumentor
비. 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초
완료
작전 완료!!
그런 다음 생성된 문서를 볼 수 있습니다. PDF 형식인 경우 이름은 기본적으로 document.pdf로 지정됩니다.
4. PHP 코드에 표준 주석 추가
PHPDocument는 소스 코드의 주석으로 문서를 생성하므로 프로그램에 주석을 추가하는 과정은 문서를 컴파일하는 과정이기도 합니다.
이러한 관점에서 PHPdoc은 좋은 프로그래밍 습관을 기르고 사양과 일반 텍스트를 사용하여 프로그램에 주석을 달도록 권장합니다. 동시에 문서 준비와 문서 간의 동기화되지 않는 문제를 어느 정도 방지합니다. 이후 업데이트.
phpdocumentor에서는 주석이 문서 주석과 문서가 아닌 주석으로 구분됩니다.
소위 문서 주석은 특정 키워드 앞에 배치되는 여러 줄의 주석입니다. 특정 키워드는 class, var 등 phpdoc에서 분석할 수 있는 키워드를 말합니다. 자세한 내용은 부록 1을 참조하세요.
키워드 앞에 오지 않거나 표준화되지 않은 주석을 비문서 주석이라고 합니다. 이러한 주석은 phpdoc에서 분석되지 않으며 생성한 API 텍스트에 나타나지 않습니다.
3.2 문서 주석 작성 방법:
모든 문서 주석은 /**로 시작하는 여러 줄의 주석으로, phpDocumentor에서는 DocBlock이라고 합니다. DocBlock은 소프트웨어 개발자가 이를 통해 이를 알 수 있도록 특정 키워드에 대한 도움말 정보를 말합니다. 그리고 그것을 사용하는 방법. PhpDocumentor는 DocBlock에 다음 정보가 포함되도록 지정합니다.
1. 기능 간략 설명 영역
2. 상세 설명 영역
3. 태그
문서 주석의 첫 번째 줄은 함수 설명 영역입니다. 텍스트는 일반적으로 이 클래스, 메서드 또는 함수의 기능을 간략하게 설명합니다. 함수 설명 텍스트는 생성된 문서의 인덱스 영역에 표시됩니다. 함수 설명 영역의 내용은 빈 줄로 끝날 수 있습니다. 함수 설명 영역이 빈 줄로 이어지면 이 부분은 주로 API의 기능과 목적을 자세히 설명합니다. 사용법 등의 예도 가능합니다. 이 섹션에서는 API 함수 또는 메서드의 일반적인 목적과 사용법을 명확히 하는 데 중점을 두고, 플랫폼 관련 정보는 일반 정보와 다르게 처리해야 합니다. 일반적인 접근 방식은 새 줄을 시작한 다음 특정 플랫폼에 대한 주의 사항이나 특별 정보를 작성하는 것입니다. 이 정보는 독자가 경계 조건, 매개 변수 범위, 중단점 등과 같은 해당 테스트 정보를 작성할 수 있을 만큼 충분해야 합니다.
그 다음에는 빈 줄과 문서 태그가 있는데, 이는 주로 호출 매개변수 유형, 반환 값 및 유형, 상속 관계, 관련 메서드/함수 등과 같은 일부 기술 정보를 나타냅니다.
문서 마킹에 관한 자세한 내용은 섹션 4: 문서 마킹을 참조하십시오.
<b> <code>와 같은 태그도 문서 주석에 사용할 수 있습니다. 자세한 내용은 부록 2를 참조하세요.
다음은 문서 주석의 예입니다.
/**
* 함수 add, 두 숫자의 추가를 구현합니다.
*
* 간단한 덧셈 계산인 이 함수는 두 숫자 a와 b를 받아들이고 그 합 c를 반환합니다.
*
* @param 정수 추가
* @param int 요약
* @return 정수
*/
함수 추가($a, $b) {
$a+$b를 반환합니다.
}
생성된 문서는 다음과 같습니다.
추가하다
정수 더하기(int $a, int $b)
[45행]
함수 add, 두 숫자의 추가를 구현합니다.
상수는 간단한 덧셈 계산입니다. 이 함수는 두 숫자 a와 b를 받아들이고 그 합계 c를 반환합니다.
매개변수
• int $a - 추가
• int $b - 요약
5. 문서 태그:
문서 태그의 사용 범위는 태그를 사용하여 수정할 수 있는 키워드 또는 기타 문서 태그를 나타냅니다.
모든 문서 태그는 각 줄의 * 뒤에 @로 시작됩니다. @ 표시가 단락 중간에 나타나면 해당 표시는 일반 내용으로 간주되어 무시됩니다.
@입장
사용 범위: 클래스, 함수, var, 정의, 모듈
이 태그는 키워드의 액세스 권한(private, public 또는 protected)을 나타내는 데 사용됩니다.
@작가
작성자를 지정하세요
@저작권
사용 범위: 클래스, 함수, var, 정의, 모듈, 사용
저작권 정보 지정
@사용되지 않음
사용 범위: 클래스, 함수, var, 정의, 모듈, 상수, 전역, 포함
사용되지 않거나 더 이상 사용되지 않는 키워드 표시
@예
이 태그는 파일 내용을 구문 분석하고 강조 표시하는 데 사용됩니다. Phpdoc은 이 태그에 지정된 파일 경로에서 파일 내용을 읽으려고 시도합니다.
@const
사용 범위: 정의
PHP에 정의된 상수를 나타내는 데 사용됩니다.
@결정적인
사용 범위: 클래스, 함수, var
키워드가 최종 클래스, 메서드 또는 특성이며 파생되거나 수정될 수 없음을 나타냅니다.
@filesource
이 태그가 현재 구문 분석된 PHP 파일의 내용을 직접 읽고 표시한다는 점을 제외하면 예제와 유사합니다.
@글로벌
이 함수에서 참조되는 전역 변수를 나타냅니다.
@ingore
문서에서 지정된 키워드를 무시하는 데 사용됩니다.
@특허
html 태그의 <a>와 동일하며 첫 번째는 URL이고 그 다음은 <a href=”http://www.baidu.com”>Baidu</a>와 같이 표시할 콘텐츠입니다.
@license http://www.baidu.com Baidu라고 쓸 수 있습니다.
@링크
라이센스와 유사
그러나 링크를 통해 문서의 모든 키워드를 가리킬 수도 있습니다.
@이름
키워드의 별칭을 지정합니다.
@패키지
사용 범위: 페이지 수준 -> 정의, 기능, 포함
클래스 수준->클래스, var, 메소드
하나 이상의 키워드를 논리적으로 그룹화하는 데 사용됩니다.
@abstrcut
현재 클래스가 추상 클래스임을 나타냅니다.
@param
함수의 매개변수 지정
@반품
메서드나 함수의 반환 포인터를 지정합니다.
@공전
키워드가 정적임을 나타냅니다.
@var
변수 유형 지정
@버전
버전 정보 지정
@todo
개선해야 할 부분이나 구현하지 말아야 할 부분을 나타냅니다.
@던지다
극단적인 경우에는 위에서 언급한 것처럼 일반 문서 태그는 각 줄의 시작 부분에 @ 를 표시해야 하며, 또한 {@ }를 사용하는 태그도 있습니다. , 특히 다음을 포함합니다.
{@링크 }
사용법은 @link와 동일합니다.
{@원천 }
함수 또는 메서드의 내용 표시
6． 일부 주석 사양
a. 의견은 다음과 같아야 합니다.
/**
* XXXXXXX
*/
형태
b. 전역 변수를 참조하는 함수의 경우 glboal 태그를 사용해야 합니다.
c. 변수의 경우 해당 유형은 var(int, string, bool...)로 표시되어야 합니다.
d. 함수는 param 및 return 태그를 통해 매개변수와 반환 값을 나타내야 합니다.
e. 2회 이상 등장하는 키워드의 경우 잉고르를 통해 중복되는 키워드는 무시하고 하나만 유지합니다.
f. 다른 함수나 클래스를 호출할 경우에는 문서를 쉽게 읽을 수 있도록 링크나 기타 태그를 사용하여 해당 부분으로 연결해야 합니다.
g. 코드 가독성을 높이기 위해 필요한 경우 문서화되지 않은 주석을 사용합니다.
h. 가능하면 문장보다는 문구를 사용하여 설명 내용을 간결하고 명확하게 유지하세요.
i. 전역 변수, 정적 변수 및 상수는 해당 태그를 사용하여 선언되어야 합니다.
7. 요약
phpDocumentor는 표준화된 주석을 작성하고 이해하기 쉽고 명확한 구조의 문서를 생성하는 데 도움이 되는 매우 강력한 자동 문서 생성 도구로, 코드 업그레이드, 유지 관리, 인계 등에 매우 유용합니다.
phpDocumentor에 대한 자세한 설명을 보려면 해당 공식 웹사이트를 방문하세요.
http://manual.phpdoc.org/View
8. 부록 부록 1:
phpdoc에서 인식되는 키워드:
포함하다
필요하다
include_once
require_once
정의하다
기능
글로벌
수업
부록 2
문서에 사용할 수 있는 태그
<비>
<코드>
<br>
<KDB>
<리>
<예비>
<ul>
<샘플>
<var>
부록 3:
정식 주석이 포함된 PHP 코드 조각:
<?php
/**
* 샘플 파일 2, phpDocumentor 빠른 시작
*
* 이 파일은 다음에 포함될 수 있는 풍부한 정보를 보여줍니다.
* DocBlocks 및 태그를 통한 코드 내 문서화.
* @저자 그렉 비버 < [email protected] >
* @버전 1.0
* @패키지 샘플
*/
// 샘플 파일 #1
/**
* phpDocumentor의 구문 분석 능력을 보여주기 위한 더미 포함 값
*/
include_once 'sample3.php';
/**
* 특수 전역 변수 선언 DocBlock
* @global 정수 $GLOBALS['_myvar']
* @name $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
*상수
*/
/**
* 첫 번째 상수
*/
정의('테스트', 6);
/**
* 두 번째 상수
*/
Define('anotherconstant', strlen('hello'));
/**
* 샘플 함수 docblock
* @global 문자열은 이 함수가 $_myvar를 사용한다는 사실을 문서화합니다.
* @staticvar 정수 $staticvar 이것이 실제로 반환되는 내용입니다.
* @param string $param1 선언할 이름
* @param string $param2 이름 값
* @return 정수
*/
함수 firstFunc($param1, $param2 = '선택적') {
정적 $staticvar = 7;
글로벌 $_myvar;
$staticvar를 반환;
}
/**
* 첫 번째 예제 클래스는 다음과 같은 패키지에 있습니다.
*파일 시작 부분의 절차적 내용
* @패키지 샘플
* @subpackage 클래스
*/
클래스 마이클래스 {
/**
* 샘플 개인 변수는 --parseprivate을 사용하여 숨길 수 있습니다.
*옵션
* @accessprivate
* @var 정수|문자열
*/
var $firstvar = 6;
/**
* @link http://www.example.com 예시 링크
* @myclass() 참조
* @uses 테스트, anotherconstant
* @var 배열
*/
var $secondvar =
정렬(
'물건' =>
정렬(
6,
17,
'아르마딜로'
),
테스트 => 다른 상수
);
/**
* 생성자는 {@link $firstvar}를 설정합니다.
*/
함수 myclass() {
$this->firstvar = 7;
}
/**
* $paramie를 기반으로 사물을 반환합니다.
* @param 부울 $paramie
* @return 정수|아기 클래스
*/
함수 parentfunc($paramie) {
만약 ($paramie) {
6을 반환합니다.
} 또 다른 {
새로운 babyclass를 반환합니다.
}
}
}
/**
* @패키지 샘플1
*/
클래스 babyclass는 myclass를 확장합니다.
/**
* 인생, 우주, 그리고 모든 것에 대한 답
* @var 정수
*/
var $secondvar = 42;
/**
* 구성 값
* @var 배열
*/
var $thirdvar;
/**
* 상위 생성자를 호출한 다음 {@link $firstvar}를 증가시킵니다.
*/
함수 베이비클래스() {
부모::myclass();
$this->firstvar++;
}
/**
* 이는 항상 myclass를 반환합니다.
* @param은 $paramie를 무시했습니다.
* @return myclass
*/
함수 parentfunc($paramie) {
새로운 myclass를 반환합니다.
}
}
?>