PHP
phpdoc

वाक्य - विन्यास

• @api
• @author [नाम] [<ईमेल पता>]
• @ कॉपीराइट <वर्णन>
• @deprecated [<"अर्थ संस्करण">] [: <"अर्थ संस्करण">] [<वर्णन>]
• @example [URI] [<विवरण>]
• {@example [URI] [: <start> .. <अंत>]}
• @inheritDoc
• @अंदर का
• {@ अनन्त [विवरण]}}
• @license [<SPDX पहचानकर्ता> | URI] [नाम]
• @ मैथोड [वापसी "टाइप"] [नाम] (["टाइप"] [पैरामीटर], [...]] [विवरण]
• @ पैकेज [स्तर 1] \ [स्तर २] \ [आदि।]
• @ अपर ["टाइप"] [नाम] [<विवरण>]
• @property ["टाइप"] [नाम] [<विवरण>]
• @return <"टाइप"> [विवरण]
• @ वह [यूआरआई | "FQSEN"] [<विवरण>]
• @since [<"सिमेंटिक वर्जन">] [<विवरण>]
• @throws ["टाइप"] [<विवरण>]
• @ तोडो [विवरण]
• @use [फ़ाइल | "FQSEN"] [<विवरण>]
• @वर ["टाइप"] [एलिमेंट_नाम] [<विवरण>]
• @version ["अर्थ संस्करण"] [<विवरण>]
• @filesource - phpDocumentor पार्सिंग परिणामों में वर्तमान फ़ाइल शामिल है
• @link [URI] [<विवरण>] - लिंक टैग संरचनात्मक तत्वों के बीच संबंध या लिंक को परिभाषित करने में मदद करता है।

टिप्पणियों

/**
 *
 */

कार्यों में मेटाडेटा जोड़ना

समारोह स्तर एनोटेशन से आईडीई को रिटर्न मान या संभावित खतरनाक कोड की पहचान करने में मदद मिलती है

/**
 * 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 प्रकारों में से एक हो सकता है, या उपयोगकर्ता-परिभाषित वर्ग, नामस्थान सहित।

चर का नाम शामिल किया जाना चाहिए, लेकिन डॉकब्लॉक केवल एक आइटम पर लागू होने पर छोड़ा जा सकता है।

मापदंडों का वर्णन

 /**
 * 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)
{
}

संग्रह

पीएसआर -5 संग्रह के लिए जेनरिक-शैली संकेतन का एक रूप प्रस्तावित करता है।

जेनरिक सिंटेक्स

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

एक संग्रह में मान भी एक और सरणी और यहां तक कि एक और संग्रह हो सकता है।

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()
]);