구를 추가하고 완전한 PHP 소스 코드를 문서화[마감]

https://stackoverflow.com/questions/1936376

20-09-2019
|

문제

나는 여러 가지 완료되면,이전 PHP 프로젝트의 많은 포함하고 싶은 것이 문서에서 javadoc/phpDocumentor 스타일입니다.

는 동안 작업을 통해 각 파일을 수동으로 강제하는 코드 리뷰와 함께 문서화하는 것이 가장 좋은 것,나는 단순히 밖으로 시간 제약에 관심있는 도구가 나를 자동화하는 작업으로 많이 가능합니다.

구에게도 생각하는 것이 이상적으로 다음과 같은 기능이 있습니다.

분석 PHP 프로젝트 트리에게 있지 않은 파일,종류 및 함수/방법(즉요소 누락 적절한 docblock comment)
는 방법을 제공하는 반 방법으로 쉽게 추가 누락 docblocks 여 을 만드는 빈 구조 그리고,이상적으로,개에서 파일 편집기(내부 또는 외부요)그래서 나를 넣을 수 있습니다.

선택 사항:

자동적인 인식의 매개변수 유형,반환 값이다.하지만 정말 필요하지 않습니다.

언어 문제 PHP 지만 내가 상상할 수 있는 C/Java 도구를 처리할 수있 PHP 파일 후 일부 조정.

감사에 대한 중대한 입력!

해결책

나는 생각한 PHP_Codesniffer 을 나타낼 수 있는 없을 때 docblock--예를 참조하십시오의 보고서에 이 페이지 (을 인용하는 하나의 사람들) :

--------------------------------------------------------------------------------
FOUND 5 ERROR(S) AND 1 WARNING(S) AFFECTING 5 LINE(S)
--------------------------------------------------------------------------------
  2 | ERROR   | Missing file doc comment
 20 | ERROR   | PHP keywords must be lowercase; expected "false" but found
    |         | "FALSE"
 47 | ERROR   | Line not indented correctly; expected 4 spaces but found 1
 47 | WARNING | Equals sign not aligned with surrounding assignments
 51 | ERROR   | Missing function doc comment
 88 | ERROR   | Line not indented correctly; expected 9 spaces but found 6
--------------------------------------------------------------------------------

난 당신이 사용할 수 있습 PHP_Codesniffer 을 얻을 적어도 모든 파일의 목록/클래스/메소드가 없는 설명서;에서 내가 기억을 생성할 수 있는 XML 로 출력하는 것이 더 쉽 분석을 사용하여 일부 자동화된 도구--할 수 있는 첫 번째 단계의 일부 docblock-generator;-)

또한,사용하는 경우 phpDocumentor 를 생성한 문서를 할 수 있습이 하나하지 않고 오류에 대한 블록 누락?

후 테스트의 몇 가지,그것을 수 있습니다-예를 들어,그것을 실행하는 클래스 파일이 많지 않은 문서,함께 --undocumentedelements 옵션과 같은 이:

phpdoc --filename MyClass.php --target doc --undocumentedelements

이 중에서 출력:

Reading file /home/squale/developpement/tests/temp/test-phpdoc/MyClass.php -- Parsing file
WARNING in MyClass.php on line 2: Class "MyClass" has no Class-level DocBlock.
WARNING in MyClass.php on line 2: no @package tag was used in a DocBlock for class MyClass
WARNING in MyClass.php on line 5: Method "__construct" has no method-level DocBlock.
WARNING in MyClass.php on line 16: File "/home/squale/developpement/tests/temp/test-phpdoc/MyClass.php" has no page-level DocBlock, use @package in the first DocBlock to create one
done

하지만,여기에,너무는 경우에도,그것은으로 유용한 도구를 보고,그것의하지 않는 것이 도움이 생성 된 docblocks...

지금,나는 알지 못한의 어떤 도구는 것이 미리 생성 된 docblocks 당신을 위해:나는 일반적으로 사용 PHP_Codesniffer 및/또는 phpDocumentor 에서 지속적인 통합 mecanism,그것을 보고 누락 docblocks,그리고,각각의 사용을 추가 누락 된 것,from his IDE...

...는 꽤 괜찮:일반적으로 몇 가지 더 누락 docblocks 매일,그렇게 작업을 수행할 수 있습에 의해 손으로 (과 이클립스 PDT 기능을 제공합을 미리 생성합 docblock 는 방법,편집할 때 특정 파일/method).

아파트에서는 난 정말 모르겠어 어떤 완전 자동화된 도구를 생성하 docblocks...그러나 나는 거의 확실히 우리는 우리를 관리할 수 있을 만드는 흥미로운 도구를 사용하여,하나:

반사 API
token_get_all 을 분석하의 소스 PHP 파일입니다.

후에 조금 더 많은 찾지만,이 블로그 포스트 (그것은 프랑스-아마 어떤 사람들은 여기에서 이해 할 수있을 것입니다) : Ajout automatique de 태그 phpDoc à 내가 보좌관 de PHP_Beautifier.
가능한 번역의 제목:"자동으로 추가 phpDoc 태그를 사용하여,PHP_Beautifier"

아이디어가 실제로 나쁘지 않다:

이 PHP_Beautifier 도구하는 경우 추가 요금이고 강력한 올 때,일부 포맷 PHP 는 코드의 잘 형식
- 내가 사용했던 그것을 많은 시간을 위한 코드가 할 수 있지 않았다는 것을 읽어도^^
고 확장 할 수 있습니다 무엇을 사용하여,그것은"필터".
- 보 PHP_Beautifier_Filter 의 목록을 위해 제공되는 필터

아이디어에서 사용되는 블로그 포스트가 연결되는 것입니다:

새로 만들 PHP_Beautifier 필터를 검색하는 다음과 같은 토큰:
- T_CLASS
- T_FUNCTION
- T_INTERFACE
추가"초안"doc-블록하기 전에,그들이 없는 경우에는 이미 중

에서 도구를 실행하려면 몇 가지 MyClass.php 파일을 처음 설치 PHP_Beautifier :

pear install --alldeps Php_Beautifier-beta

그런 다음 다운로드하려면 필터는 디렉토리에서 작업 (수 있에 넣어 기본 디렉토리의 코스) :

wget http://fxnion.free.fr/downloads/phpDoc.filter.phpcs
cp phpDoc.filter.phpcs phpDoc.filter.php

그리고,그 후,나는 새로운 생성 beautifier-1.php 스크립트 (는 무엇을 기반으로의 제안에서 블로그 포스트가 연결되어 다시 한번), 는 것입니다:

드의 콘텐츠에 나 MyClass.php 파일
Instanciate PHP_Beautifier
추가 필터를 아름답게 코드
추가 phpDoc 필터 우리는 그냥 다운로드
을 아름답게 우리의 파일 echo 표준 출력됩니다.

코드 beautifier-1.php 스크립트는 다음과 같다:
(다시 한번 가장 큰 부분은 복사하여 붙여넣기에서 블로그 포스트;나만을 번역하의 의견,그리고 변경의 몇 가지 작은 것들)

require_once 'PHP/Beautifier.php';

// Load the content of my source-file, with missing docblocks
$sourcecode = file_get_contents('MyClass.php');

$oToken = new PHP_Beautifier(); 

// The phpDoc.filter.php file is not in the default directory,
// but in the "current" one => we need to add it to the list of
// directories that PHP_Beautifier will search in for filters
$oToken->addFilterDirectory(dirname(__FILE__));

// Adding some nice filters, to format the code
$oToken->addFilter('ArrayNested');  
$oToken->addFilter('Lowercase');        
$oToken->addFilter('IndentStyles', array('style'=>'k&r'));

// Adding the phpDoc filter, asking it to add a license
// at the beginning of the file
$oToken->addFilter('phpDoc', array('license'=>'php'));

// The code is in $sourceCode
// We could also have used the setInputFile method,
// instead of having the code in a variable
$oToken->setInputString($sourcecode);        
$oToken->process();

// And here we get the result, all clean !              
echo $oToken->get();

참고 또한 나를 경로는 두 개의 작은 것에 phpDoc.filter.php, 을 방지하기 위해,경고 및 알...
해당하는 패치 다운로드할 수 있습기: http://extern.pascal-martin.fr/so/phpDoc.filter-pmn.patch

지금는 경우에,우리는 실행 beautifier-1.php 스크립트:

$ php ./beautifier-1.php

로 MyClass.php 파일 initialy 포함 이 코드:

class MyClass {
    public function __construct($myString, $myInt) {
        // 
    }

    /**
     * Method with some comment
     * @param array $params blah blah
     */
    public function doSomething(array $params = array()) {
        // ...
    }

    protected $_myVar;
}

여기는 종류의 결과 우리는-번 우리의 파일을 아름답게:

<?php
/**
 *
 * PHP version 5
 *
 * LICENSE: This source file is subject to version 3.0 of the PHP license
 * that is available through the world-wide-web at the following URI:
 * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
 * the PHP License and are unable to obtain it through the web, please
 * send a note to license@php.net so we can mail you a copy immediately.
 * @category   PHP
 * @package
 * @subpackage Filter
 * @author FirstName LastName <mail>
 * @copyright 2009 FirstName LastName
 * @link
 * @license     http://www.php.net/license/3_0.txt  PHP License 3.0
 * @version    CVS: $Id:$
 */


/**
 * @todo Description of class MyClass
 * @author 
 * @version 
 * @package 
 * @subpackage 
 * @category 
 * @link 
 */
class MyClass {

    /**
     * @todo Description of function __construct
     * @param  $myString 
     * @param  $myInt
     * @return 
     */
    public function __construct($myString, $myInt) {
        //

    }
    /**
     * Method with some comment
     * @param array $params blah blah
     */
    public function doSomething(array $params = array()) {
        // ...

    }

    protected $_myVar;
}

우리가 참고 할 수 있습니다:

라이센스 블록의 시작 부분에서 파일
이 docblock 추가된 것에 MyClass 클래스
이 docblock 추가된 것에 __construct 방법
이 docblock 에 doSomething 이미 존재하에서 우리의 코드:그것은 제거되었습니다.
몇몇 @todo 태그^^

지금,그것은 완벽하지 않고,물론:

지 않는 문서에는 모든 물건을 우리는 할 수있는 그것은 너무
- 예를 들어,여기에,그것은 문서화 protected $_myVar
그것을 향상시켜 주지 않는다면 기존 docblocks
고 그것은 열리지 않는 파일에서 그래픽 편집기
- 하지만 훨씬 더 어려울 것입,내 생각...

하지만 난 정말 이 아이디어가 사용될 수 있습을 시작점으로 무언가에 더 많은 흥미로운:

에 대한 물건을 얻을하지 않는 설명:를 추가하는 새로운 태그 인정될 것이 너무 열심히 일하지 않도
- 당신은 단지 그들을 추가해야 목록에서 시작 부분의 필터
강화하는 기존 docblocks 어려울 수 있을 인정
좋은 일이 될 수 있는 완전 자동화
Eclipse 를 이용하여 PDT,어쩌면 이 설정할 수 있습으로 외부 도구, 가 있습니다,그래서 우리는 적어도 그것을 실행에서 우리의 IDE?

다른 팁

이후 PHPCS 이미 언급에 던져 반영 API 를 확인 DocBlocks.이 문서는 아래 링크는 짧은 튜토리얼을 수 있는 방법에 접근 방식의 문제는:

http://www.phpriot.com/articles/reflection-api

도 배 패키지 PHP_DocBlockGenerator 는 파일을 만들 수 있습니다 페이지 블록고 DocBlocks 를 포함한,전역 변수,함수,매개변수,수업,상수,특성 및 방법(다른 것들).

php-추적-위버 할 수 있는 계기를 생성하 docblocks 매개변수 유형,차감을 통해 런타임이 분석.

사용할 수 있습니다 코드 스니퍼 PHP 의 코드를 테스트하여 사전 정의된 일련의 코딩 가이드라인.그것은 또한 확인을 위해 누락 docblocks 과 보고서를 생성을 식별하는 데 사용할 수 있습니다.

1.4.x 버전의 phpDocumentor 가-ue 옵션(--undocumentedelements)[1],을 일으킬 것입니다 언급되지 않음 요소로 나열됩 경고 errors.html 페이지 생성하는 동안 doc 실행됩니다.

또한,PHP_DocBlockGenerator[2]에서 보이는 배처럼을 생성할 수 있습 누락 docblocks 습니다.

[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#using.command-line.undocumentedelements

[2] -- http://pear.php.net/package/PHP_DocBlockGenerator

우리가 사용하는 codesniffer 이러한 기능을 위해서,작품을 사용하여 표준 배나 젠 표준입니다.그것은 당신을 허용하지 않습니다 파일을 편집 할 수있는 비행에,그러나 확실히 줄 것입니다 당신 목록은,선을 가진 및 설명의 어떤 종류의 docblock 가 없습니다.

HTH, Jc

아무 생각하는 경우 그것은 어떤 도움이지만,이 경우 Codesniffer 수 있는 함수와 방법을 제 PHP IDE(제 PHPEd)할 수 있습 쉽게 검사 및 비계의 PHPDoc 의견에 대한 각 기능입니다.

단순히 형식 /** 위의 각 기능을 눌러 입력하고 PHPEd 을 자동 완성하는 코드 @param1, @param1, @return, 니다,등등.가 올바르게 준비한 추가 설명입니다.여기에 첫 번째 중 하나에서 보았을 제공하기 위해 예를 들어:

  /**
  * put your comment here...
  * 
  * @param mixed $url
  * @param mixed $method
  * @param mixed $timeout
  * @param mixed $vars
  * @param mixed $allow_redirects
  * @return mixed
  */
  public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)

이것은 쉽게 조정하기:

  /**
  * Retrieves a file using the cURL extension
  * 
  * @param string $url
  * @param string $method
  * @param int $timeout
  * @param array $vars parameters to pass to cURL
  * @param int $allow_redirects boolean choice to follow any redirects $url serves up
  * @return mixed
  */
  public static function curl_get_file_contents($url, $method = 'get', $timeout = 30, $vars = array(), $allow_redirects = true)

지 정확히 자동화된 솔루션이지만,충분히 빠른 나 게으른 개발자:)

당신이 원하는 실제 자동화의 문제에서 작성"과"유형의 데이터가?

이 DMS 소프트웨어 재 설계 Toolkit 하도록 구성할 수 있었습니다.

구문 분석,원본 텍스트처럼 컴파일러,하 구축 내부의 컴파일러 구조를 구현할 수 있습 임의의 분석을 수정하여 그 구조물,그리고 다음 재생("prettyprint")원본 텍스트를 변경된 구조에 따라 변경됩니다.그것을 심지어는 의견 유지하고 서식을 지정하는 원본 텍스트할 수 있습니다 물론 추가로 삽입한 의견하고 그들이 나타납니다 이것은 당신의 기본 목표입니다.DMS 이를 포함하여 많은 언어 PHP

당신이 무엇을 하고 싶은 것이 분석 서 PHP 파일을 찾은 모든 클래스/메소드를 생성"과"의견을 해야 하는 것 entity(차이를 위해 클래스와 방법,right?) 다음 확인을 해당 의견이 실제로 존재에서 컴파일러 구조물입니다.그렇지 않은 경우,단순히 삽입합니다.PrettyPrint 최종 결과입니다.기 때문에 그것은에 액세스할 수 있는 컴파일러 구조물을 대표하는 코드,그것은 어렵지 않을 것을 생성하는 매개변수와는 반환한 정보로서,당신은 제안했다.무엇을 할 수 없는 물론 생성에 대한 의견 intendend 목적;하지만 그것을 생성할 수 있는 자리 표시자를 채우기 위해서다.

가 큰 배치의 자동화의 docblock 고정 최근에 올바른 답을 위 kwith 어떤 상황에 맞는 변경합니다.그것은 해킹이지만,저는 여기서 다시 연결하는 경우 유용한 다른 사람에게 미래입니다.기본적으로,그것은 기본적인 분석에 코멘트 블록 토큰 PHP 내에 아름답게.

https://gist.github.com/israelshirk/408f2656100196e73367

라이센스 : CC-BY-SA ~와 함께 속성

제휴하지 않습니다 StackOverflow