PHPDoc

PHPDoc은 Javadoc을 PHP 프로그래밍 언어로 변형 한 것입니다 그것은 여전히 PHP 코드에 대한 비공식적 인 표준이지만, 공식화되는 과정

외부 문서 생성기와 같은 것을 허용합니다 사실상의 표준 구현 인 phpDocumentor는 생성하기 위해 API 문서화 및 Zend Studio, NetBeans, JetBrains PhpStorm, ActiveState Komodo 편집 및 IDE, PHPEdit 및 Aptana Studio 느슨하게 입력 된 변수 유형 및 기타 모호함 해석 향상된 코드 완성, 힌팅 및 디버깅을 제공합니다 PHPDoc은 객체 지향 및 절차 적 코드의 문서화를 지원합니다 2013 년 8 월 13 일 PHP 프레임 워크 상호 운용성 그룹은 PHPDoc의 공식 사양 PHPDoc의 구성 요소 = DocBlock = DocBlock은 확장 된 C ++ 스타일의 PHP입니다

"/ **"로 시작하고 모든 행의 시작 부분에 "*"가있는 주석 DocBlocks는 문서화중인 요소 앞에옵니다 DocBlock 내의 모든 라인 *로 시작하지 않는 것은 무시됩니다 "foo ()"함수를 문서화하려면 DocBlock을 함수 바로 앞에 두십시오 declaration :이 예제는 DocBlock을에 적용 할 것이다

"define ( 'aklo', 2);" "function foo ()"대신에 : define () 문, 함수, 클래스, 클래스 메서드 및 클래스 변수, include () 문 및 전역 변수는 모두 문서화 할 수 있습니다 문서화 될 수있는 소스 코드 DocBlock은 세 가지 기본 세그먼트 이 순서대로 : 짧은 설명 상세 설명 태그 간단한 설명은 첫 번째 줄에서 시작하고 빈 줄 또는 마침표 한 단어 안의 마침표는 무시됩니다 짧은 경우 설명은 세 줄 이상이되며 첫 줄만 찍은 긴 설명은 원하는 수만큼 계속되며 표시 형식에 HTML 마크 업을 포함합니다

다음은 샘플 DocBlock입니다 짧고 긴 설명 : 선택 사항으로 모든 태그의 단락 처음 단락이 시작되지 않으면주의하십시오 phpDocumentor는 DocBlock이 단순한 double을 사용하고 있다고 가정합니다 줄 바꿈을 사용하여 단락 나누기를 다음과 같이 정의하십시오

다음은 phpDocumentor를 사용하는 예입니다 JavaDoc도 지원합니다 명령 행 옵션 -j, –javadocdesc를 통해 DocBlock 형식 인해 비 XHTML과 호환되지 않는 p 태그를 사용하는 경우이 문제를 피하는 것이 좋습니다 가능한 언제든지 구문 phpDocumentor는 모든 것을 변환합니다

공백을 긴 설명의 단일 공백에 넣고 단락 나누기를 사용합니다 개행을 정의하거나, 다음 절에서 설명하는 것처럼 DocBlock 설명 세부 정보 일부 파서에서는 길고 짧은 DocBlock에 대한 설명은 다음을 결정하는 몇 가지 선택 HTML 태그에 대해 구문 분석됩니다 추가 서식 모든 HTML이 허용되는 것은 아니기 때문에 일반적으로 일반 텍스트 또는 더 많은 콘텐츠 특정 태그로 변환됩니다

예를 들어, a 태그는 DocBlock으로 변환 될 수 있습니다 다음은에 의해 지원되는 태그 목록입니다 phpDocumentor : – 강조 / 굵은 글씨체 – 이것을 사용하여 PHP 코드를 둘러싸고, 일부 변환기가 강조 표시합니다 – 단단한 줄 바꿈은 일부 변환기에서 무시 될 수 있습니다 – 기울임 꼴로 표시 / 중요하게 표시 – 키보드 입력 / 화면 표시를 나타냅니다

– 목록 항목 – 정렬 된 목록 – 모든 단락을 묶는 데 사용되는 경우 텍스트로 간주됩니다 – 줄 바꿈 및 간격을 유지하고 모든 태그가 텍스트라고 가정합니다 – 샘플 또는 예제를 나타냅니다 – 정렬되지 않은 목록 – 변수 이름을 나타냅니다 ""텍스트가있는 드문 경우입니다 DocBlock에 필요하다면,>에서와 같이 이중 분리 문자를 사용하십시오

phpDocumentor 또는 자동으로 실제 텍스트 ""로 번역합니다 그리고 위에 나열된 HTML을 무시하고 무시하십시오 DocBlock 템플릿 DocBlock 템플릿의 목적은 중복 입력을 줄입니다 예를 들어 많은 수의 클래스 변수가 비공개로 설정하면 DocBlock 템플릿을 사용하여 비공개로 표시 할 수 있습니다 DocBlock 템플릿은 템플릿에서 발견 된 모든 일반 DocBlock을 간단하게 보강합니다

블록 DocBlock 템플릿은 고유합니다 정상적인 DocBlock에서 헤더로 다음은 가장 기본적인 DocBlock입니다 template : 이것을 DocBlock으로 표시하는 텍스트 템플릿은 "/ ** # @ +"입니다 – 6 자 모두 입력해야합니다

DocBlock 템플릿은 다음과 같습니다 끝나는 템플릿 마커까지 문서화 가능한 모든 요소에 적용 : phpDocumentor를 사용하려면 8 개의 문자가 모두 ""로 나타나야합니다 템플릿으로 인식하십시오 페이지 레벨 DocBlocks 페이지 레벨 DocBlock은 요소를 선행 할 수없는 유일한 DocBlock입니다 파일을 선행 할 방법이 없기 때문에 문서화하고 있습니다

이 문제를 해결하려면 문제, phpDocumentor가 페이지 수준 DocBlock을 파싱하는 방법 특정 DocBlock 파일을 페이지 레벨 DocBlock으로 정황 이 마지막 예제에는 하나의 DocBlock이 있고 파일의 첫 번째 DocBlock이지만 페이지 레벨 DocBlock이 아닙니다 어떻게 phpDocumentor는 페이지 레벨 DocBlock과 다른 DocBlock? 단순 : phpDocumentor 버전 122에서는 페이지 레벨 DocBlock은 파일에있는 첫 번째 DocBlock입니다

@package 태그 그러나이 예제는 testphp에서 WARNING과 같은 경고를 발생시킵니다 8 행 : 페이지 수준 DocBlock이 "define almost"앞에오고 다른 DocBlock을 사용하여 소스 요소를 문서화하십시오 추가하여 경고를 제거 할 수 있습니다

문서를 다음과 같이 정의합니다 이제 페이지에 설명서가 있으며 정의에는 자체 문서가 있습니다 DocBlock은 페이지 레벨 DocBlock입니다 그리고 둘 다인 경우에만 : 파일의 첫 번째 DocBlock 다음 중 하나 : @package 태그 포함 또는 문서화 가능한 PHP에 대해 다른 DocBlock이 즉시 따라옵니다 요소 페이지 레벨 DocBlock은 표준 phpDocumentor 태그와 다음 태그 @package @subpackage phpDocumentor는 첫 번째 예제와 같은 파일을 문서화하지 않습니다

파일에 문서화 가능한 PHP 요소가 적어도 하나 이상 있어야합니다 = 태그 = 태그는 접두사가 "@"인 단일 단어입니다 상징 태그는 파서에게 정보를 표시하고 표시를 수정하는 방법을 알려줍니다 IDE가 변수 유형을 정의 할 수 있도록 허용합니다

모든 태그 선택 사항이지만 태그를 사용하는 경우에는 구문 분석 할 특정 요구 사항이 있습니다 정확히 또한 일부 파서는 두 개의 추가 인라인 태그 : {@id} : 튜토리얼 및 {@toc}을 사용하여 {@id}에서 목차를 생성하는 데 사용됩니다 파일 같은 기능을하는 HTML 태그처럼 생각하세요

PHPDoc 태그에 대한 자세한 설명은 nualphpdocorgPHPtutorial_tagspkghtml = 패키지 = 패키지의 역할과 @package를 사용하는 방법을 이해하려면 PHP의 패키징 뒤에 숨어있는 논리를 알아야합니다

구조화 된 프로그래밍에 대한 탐구 함수, 그리고 클래스, 그리고 마지막으로 패키지의 발명에 이르기까지 전통적으로 재사용 가능한 소프트웨어 모듈은 변수의 모음이었습니다 다른 소프트웨어 패키지에서 사용할 수있는 상수 및 기능을 제공합니다 PHP는 이 모델의 예입니다 토큰 라이저 확장과 같은 상수 및 기능 하나는 생각할 수있다

패키지로서의 토큰 화 도구 확장 : 완전한 데이터, 변수 및 다른 프로그램에서 사용할 수있는 기능 구조화 된 형식 이 모델은 물론 객체 또는 클래스입니다 클래스에는 변수와 기능 단일 클래스는 관련된 함수와 변수를 함께 묶습니다 재사용 할 수 있습니다 phpDocumentor는 두 개의 패키지를 정의합니다

방법 : 함수, 상수 및 전역 변수는 파일로 그룹화되어 차례로 패키지로 그룹화됩니다 페이지 레벨 DocBlock의 @package 태그 메소드 및 클래스 변수는 클래스로 그룹화되며 차례로 그룹화됩니다 클래스 DocBlock에있는 패키지로이 두 패키지 정의는 다음과 같습니다 독특한 즉, 다른 클래스를 가질 수 있습니다

패키지를 포함하고있는 파일의 패키지 또한보십시오 ApiGen phpDocumentor 문서 생성기의 Doxygen 비교 참조 ^ abc PHP-FIG : PSR 작업 초안 – s : githubcomfig-standardsmasterphpdocmd ^ "@return tag – phpDocumentor" 외부 링크 DocBlox phpDocumentor

org