PHPDoc: @ ग्रेट शून्य आवश्यक है?

Question 1

क्या वास्तव में ऐसा कुछ करना आवश्यक है:

/**
 * ...
 * 
 * @return void
 */

मेरे पास काफी कुछ विधियां हैं, जिनमें रिटर्न वैल्यू नहीं है, और यह टिप्पणी में ऐसा कुछ डालने के लिए वास्तव में बेमानी लगता है। क्या इसे छोड़ने के लिए इसे बुरा रूप माना जाएगा?

Question 2

यदि यह प्रलेखन के लिए इसे स्पष्ट करता है, तो इसे अंदर छोड़ दें, लेकिन यह कड़ाई से आवश्यक नहीं है। यह पूरी तरह से व्यक्तिपरक निर्णय है।

निजी तौर पर, मैं इसे छोड़ दूंगा।

संपादित
मैं सही खड़े हो जाओ। थोड़ा गुगली करने के बाद, विकिपीडिया पृष्ठ कहता है:

@ ग्रेट [प्रकार का वर्णन] इस टैग का उपयोग निर्माणकर्ताओं या विधियों के लिए शून्य रिटर्न प्रकार के साथ परिभाषित नहीं किया जाना चाहिए ।

Phpdoc.org वेबसाइट कहती है:

@return datatype description
@return datatype1 | datatype2 विवरण

@Return टैग का उपयोग फ़ंक्शंस या विधियों के रिटर्न वैल्यू के दस्तावेज़ के लिए किया जाता है। @returns अन्य स्वचालित दस्तावेज़ों के टैग प्रारूपों का समर्थन करने के लिए @return के लिए एक उपनाम है

डेटाटाइप एक वैध PHP प्रकार (इंट, स्ट्रिंग, बूल, आदि) होना चाहिए , वस्तु के प्रकार के लिए एक वर्ग का नाम, या "मिश्रित"। यदि आप स्पष्ट रूप से कई संभावित रिटर्न प्रकार दिखाना चाहते हैं, तो उन्हें रिक्त स्थान के बिना पाइप-सीमांकित सूचीबद्ध करें (उदाहरण के लिए "@return | string")। यदि @return टैग में एक वर्ग नाम का उपयोग डेटाटाइप के रूप में किया जाता है, तो phpDocumentor स्वचालित रूप से उस वर्ग के दस्तावेज़ का लिंक बना देगा। इसके अलावा, यदि कोई फ़ंक्शन कई संभावित मान लौटाता है, तो उन्हें अलग करें | चरित्र, और phpDocumentor रिटर्न मान में किसी भी वर्ग के नाम का पता लगाएगा। phpDocumentor बिना विवरण के वैकल्पिक विवरण प्रदर्शित करेगा।

सू ... इसके आधार पर, मैं कहूंगा कि शून्य को छोड़ दें। यह गैर-मानक है, कम से कम।

Question 3

PhpDocumentor के अनुसार, @return शून्य मान्य है:

http://www.phpdoc.org/docs/latest/guides/types.html#keywords

... इस प्रकार का आमतौर पर केवल एक विधि या फ़ंक्शन के रिटर्न प्रकार को परिभाषित करते समय उपयोग किया जाता है। मूल परिभाषा यह है कि इस प्रकार से संकेतित तत्व में कोई मान नहीं होता है और उपयोगकर्ता को किसी भी पुनः प्राप्त मूल्य पर भरोसा नहीं करना चाहिए।

उदाहरण के लिए:
 /**
  * @return void
  */
 function outputHello()
 {
     echo 'Hello world';
 }
उदाहरण में, कोई रिटर्न स्टेटमेंट निर्दिष्ट नहीं है और इस प्रकार रिटर्न वैल्यू निर्धारित नहीं है।

स्रोत: http://www.phpdoc.org/docs/latest/for-users/phpdoc/types.html ( संग्रहीत पृष्ठ )।

Question 4

मुझे अपने जवाब को संपादित करना होगा क्योंकि मैंने हाल ही में कुछ सीखा है।

के @return voidबजाय का उपयोग करने का @return nullएक बहुत ही विशेष अर्थ है, PHP कोड के निम्नलिखित दो उदाहरणों पर विचार करें।

<?php

/**
 * @return void
 */
function return_never() {
    echo "foo";
}

/**
 * @return null|string
 */
function return_sometimes() {
    if ($this->condition()) {
        return "foo";
    }
}

पहले उदाहरण में PHP वास्तव में वापस आ जाएगी NULL, क्योंकि PHP हमेशा लौटती है NULL। लेकिन लौटाया गया मूल्य कॉलर के लिए किसी काम का नहीं है क्योंकि यह इस बारे में कुछ नहीं कहता है कि फ़ंक्शन ने क्या किया। IDE @return voidडेवलपर को इंगित करने के लिए प्रलेखित जानकारी का उपयोग कर सकता है कि रिटर्न मान का उपयोग किया जाता है जो बिना उद्देश्य के कार्य करता है।

<?php

$foo1 = return_never();

$foo2 = return_sometimes();

पहला कॉल सेंसलेस है क्योंकि वेरिएबल हमेशा रहेगा NULL, दूसरे में वास्तव में कुछ हो सकता है। यह और भी दिलचस्प होता जा रहा है यदि हम फ़ंक्शन कॉल को एक सशर्त में डालते हैं।

<?php

if (($foo1 = return_never())) {
    // Dead code
    var_dump($foo1);
}

if (($foo2 = return_sometimes())) {
    var_dump($foo2);
}

जैसा कि आप देख सकते हैं, @return void इसके उपयोग के मामले हैं और यदि लागू हो तो इसका उपयोग किया जाना चाहिए।

यह भी ध्यान दें कि यह आगामी PHP PSR-5 मानक का एक हिस्सा होने जा रहा है।^[1]

[१] http://www.php-fig.org/psr/

Question 5

Php 7.1 के रूप में, voidएक वैध रिटर्न प्रकार है और इसे किसी फ़ंक्शन पर लागू किया जा सकता है।

मैं हमेशा इसे डॉकब्लॉक पर जोड़ूंगा।

इसे लिखने का एक अन्य लाभ, उन voidविधियों से विधियों को अलग करना है जो कुछ भी वापस कर सकते हैं, लेकिन @returnलापरवाही से डॉकब्लॉक पर एक प्रविष्टि नहीं है ।

Question 6

यहाँ बताया गया है कि मैं कैसे PhpDocumentor एनोटेशन का उपयोग और उपयोग करता हूँ:

<?php

/**
 * This method always returns string.
 * @return string
 */
public function useCase1()
{
    return 'foo';
}

/**
 * This method returns 2 data types so list them both using pipeline separator.
 * @return string|false
 */
public function useCase2()
{
    if ($this->foo === 1) {
        return 'foo';
    }
    return false;
}

/**
 * This method performs some operation and does not return anything so no return
 * annotation is needed.
 */
public function useCase3()
{
    $this->doOperation();
    $this->doAnotherOperation();
}

/**
 * If condition passes method returns void. If condition does not pass it returns
 * nothing so I think that specifying the return annotation with void is in space. :)
 * @return void
 */
public function useCase4()
{
    if ($this->foo === 1) {
        $this->doOperation();
        return;
    }
    $this->doAnotherOperation();
}

Question 7

व्यक्तिगत रूप से, मुझे लगता है कि इससे बड़ी बात यह है कि एक समारोह रिटर्न का दस्तावेजीकरण करना महत्वपूर्ण है। वर्तमान में मानकों में फ़ंक्शंस के लिए कोई डॉक्यूमेंटेशन नहीं है जो कभी नहीं लौटता है .... इसलिए एक रिटर्न शून्य यह कहने का तरीका है कि हाँ यह फ़ंक्शन वास्तव में वापस आता है।

इस कोड ब्लॉक पर विचार करें

<?php

/**
 * @return void
 */
function return_void() {
    echo "foo";
}

/**
 * @return null|string
 */
function return_sometimes() {
    if ($this->condition()) {
        return "foo";
    }
}

/**
* This function actually doesnt return at all - it kills the script
**/
function noreturn() {
     //do somthing then
     die(); //or exit()
}

स्निपेट का विस्तार करें

स्पष्ट रूप से @ ग्रेट का उपयोग कम से कम फ़ंक्शन को वापस लौटने का संकेत देता है