PHP
PHPDoc

통사론

• @api
• @author [이름] [<이메일 주소>]
• @copyright <description>
• @deprecated [< "Semantic Version">] [: < "Semantic Version">] [<description>]
• @example [URI] [<description>]
• {@example [URI] [: <start> .. <end>]}
• @inheritDoc
• @내부의
• {@ 내부 [설명]}}
• @license [<SPDX 식별자> | URI] [이름]
• @method [return "Type"] [name] ([ "Type"] [매개 변수], [...]) [설명]
• @ 패키지 [레벨 1] \ [레벨 2] \ [기타]
• @param [ "Type"] [name] [<description>]
• @property [ "Type"] [name] [<description>]
• @return < "Type"> [description]
• @see [URI | "FQSEN"] [<description>]
• @since [< ""시맨틱 버전 ">] [<description>]
• @throws [ "Type"] [<description>]
• @ 토드 [설명]
• @uses [파일 | "FQSEN"] [<description>]
• @var [ "Type"] [element_name] [<description>]
• @version [ "Semantic Version"] [<description>]
• @filesource - 현재 파일을 phpDocumentor 또는 구문 분석 결과에 포함합니다.
• @link [URI] [<description>] - 링크 태그는 구조 요소 간의 관계 또는 링크를 정의하는 데 도움이됩니다.

비고

/**
 *
 */

함수에 메타 데이터 추가

함수 레벨 주석은 IDE가 반환 값 또는 잠재적으로 위험한 코드를 식별하는 데 도움이됩니다.

/**
 * Adds two numbers together.
 *
 * @param Int $a First parameter to add
 * @param Int $b Second parameter to add
 * @return Int
 */
function sum($a, $b)
{
    return (int) $a + $b;
}

/**
 * Don't run me! I will always raise an exception.
 *
 * @throws Exception Always
 */
function dangerousCode()
{
    throw new Exception('Ouch, that was dangerous!');
}

/**
 * Old structures should be deprecated so people know not to use them.
 *
 * @deprecated
 */
function oldCode()
{
    mysql_connect(/* ... */);
}

파일에 메타 데이터 추가하기

파일 수준 메타 데이터는 파일 내의 모든 코드에 적용되므로 파일의 맨 위에 배치해야합니다.

<?php

/**
 * @author John Doe ([email protected])
 * @copyright MIT
 */

상위 구조에서 메타 데이터 상속

클래스가 다른 클래스를 확장하고 동일한 메타 데이터를 사용하는 경우 @inheritDoc 제공하면 동일한 문서를 사용할 수있는 간단한 방법입니다. 여러 클래스가 기반을 상속하는 경우 영향을받는 하위 항목을 변경해야합니다.

abstract class FooBase
{
    /**
     * @param Int $a First parameter to add
     * @param Int $b Second parameter to add
     * @return Int
     */
    public function sum($a, $b) {}
}

class ConcreteFoo extends FooBase
{
    /**
     * @inheritDoc
     */
    public function sum($a, $b)
    {
        return $a + $b;
    }
}

변수 설명하기

@var 키워드는 다음의 유형과 사용법을 설명하는 데 사용할 수 있습니다.

• 클래스 속성
• 지역 변수 또는 전역 변수
• 클래스 또는 전역 상수

class Example {
    /** @var string This is something that stays the same */
    const UNCHANGING = "Untouchable";

    /** @var string $some_str This is some string */
    public $some_str;

    /**
     * @var array $stuff    This is a collection of stuff
     * @var array $nonsense These are nonsense
     */
    private $stuff, $nonsense;

    ...
}

유형은 내장 PHP 유형 또는 네임 스페이스를 포함한 사용자 정의 클래스 중 하나 일 수 있습니다.

변수의 이름을 포함해야하지만 docblock이 하나의 항목에만 적용되는 경우 생략 할 수 있습니다.

매개 변수 설명

 /**
 * Parameters
 * 
 * @param  int    $int
 * @param  string $string
 * @param  array  $array
 * @param  bool   $bool
 */
function demo_param($int, $string, $array, $bool)
{
}

 /**
 * Parameters - Optional / Defaults
 *
 * @param  int    $int
 * @param  string $string
 * @param  array  $array
 * @param  bool   $bool
 */
function demo_param_optional($int = 5, $string = 'foo', $array = [], $bool = false)
{
}

/**
 * Parameters - Arrays
 * 
 * @param array          $mixed
 * @param int[]          $integers
 * @param string[]       $strings
 * @param bool[]         $bools
 * @param string[]|int[] $strings_or_integers
 */
function demo_param_arrays($mixed,$integers, $strings, $bools, $strings_or_integers)
{
}

/**
 * Parameters - Complex
 * @param array $config 
 * <pre>
 * $params = [
 *         'hostname'     => (string) DB hostname. Required.
 *         'database'     => (string) DB name. Required.
 *         'username'     => (string) DB username. Required.
 * ]
 * </pre>
 */
function demo_param_complex($config)
{
}

컬렉션

PSR-5 는 수집을위한 제네릭 스타일 표기법의 형식을 제안합니다.

제네릭 구문

Type[]
Type<Type>
Type<Type[, Type]...>
Type<Type[|Type]...>

Collection의 값은 다른 배열 일 수도 있고 다른 Collection 일 수도 있습니다.

Type<Type<Type>>
Type<Type<Type[, Type]...>>
Type<Type<Type[|Type]...>>

예제들

<?php

/** 
 * @var ArrayObject<string> $name 
 */
$name = new ArrayObject(['a', 'b']);

/** 
 * @var ArrayObject<int> $name 
 */
$name = new ArrayObject([1, 2]);

/** 
 * @var ArrayObject<stdClass> $name 
 */
$name = new ArrayObject([
    new stdClass(), 
    new stdClass()
]);

/** 
 * @var ArrayObject<string|int|stdClass|bool> $name 
 */
$name = new ArrayObject([
    'a', 
    true, 
    1, 
    'b', 
    new stdClass(), 
    'c', 
    2
]);

/**
 * @var ArrayObject<ArrayObject<int>> $name 
 */
$name = new ArrayObject([
    new ArrayObject([1, 2]), 
    new ArrayObject([1, 2])
]);

/** 
 * @var ArrayObject<int, string> $name 
 */
$name = new ArrayObject([
    1 => 'a', 
    2 => 'b'
]);

/** 
 * @var ArrayObject<string, int> $name 
 */
$name = new ArrayObject([
    'a' => 1, 
    'b' => 2
]);

/** 
 * @var ArrayObject<string, stdClass> $name 
 */
$name = new ArrayObject([
    'a' => new stdClass(), 
    'b' => new stdClass()
]);