नेटबीन्स में कक्षा दस्तावेज के लिए उचित तरीका PHP

Question

रखरखाव और आईडीई कक्षा ऑटो-पूर्णता और सदस्य संकेत देने की आसानी के कारण, मैंने अपनी परियोजना में PHPDoc का उपयोग किया है। इस उदाहरण वर्ग को देखते हुए:

class my_class { 
    public $id; 
    public $name; 
    public $number; 

    public function __construct() { 
     //Do something 
    } 

    public function Rename($name) { 
     $this->name = $name; 
    } 
} 

मैं कक्षा प्रलेखन ही है, जो वर्ग घोषणा से ऊपर है के साथ सभी गुण ($id, $name और $number) दस्तावेज़ के लिए पसंद करते हैं, और उसके बाद के तरीकों के लिए दस्तावेज़ जगह (यदि आवश्यक हो) ऊपर प्रत्येक विधि। यहाँ है कि मैं क्या अंततः मेरी कक्षा की तरह देखना चाहते हैं:

/** 
* Represents an example class for Stackoverflow 
* 
* @property int $id The id of the object 
* @property string $name The name of the object 
* @property int $number The number of the object 
*/ 
class my_class { 
    public $id; 
    public $name; 
    public $number; 

    public function __construct() { 
     //Do something 
    } 

    /** 
    * Renames the object 
    * @param string $name Name to rename object 
    */ 
    public function Rename($name) { 
     $this->name = $name; 
    } 
} 

यह ठीक है कि मैं क्या प्रलेखन के रूप में शामिल किया जाना पसंद है, तथापि Netbeans 'स्वत: पूर्ण सही ढंग से संचालित करने के लिए, के रूप में यह प्रत्येक संपत्ति दो बार सूचीबद्ध करता है विफल रहता है। उदाहरण के लिए, यदि मैं $my_class_object->i लिखना शुरू करता हूं तो ऑटो-पूर्ण दो $ आईडी गुणों की सूची देगा: जैसा कि मेरे PHPDoc में वर्णित है, और दूसरा "PHPDoc नहीं मिला" के साथ अज्ञात चर के रूप में वर्णित है।

एक समाधान है जो नेटबींस मुद्दे को हल करने के लिए काम करता है - प्रत्येक संपत्ति के ऊपर @var PHPDoc ब्लॉक जोड़ें, हालांकि मुझे लगता है कि यह अनावश्यक रूप से मेरी कक्षा को अपनाना चाहता है, खासकर मेरे कुछ वर्ग जिनमें 10+ गुण हैं।

क्या मेरे दोनों मुद्दों (स्वच्छ दस्तावेज़, उचित नेटबीन संकेत) के लिए एक अच्छा [अच्छा] समाधान है, या क्या मैं इस बारे में गलत तरीके से जा रहा हूं?

Answer 1

"संपत्ति" टैग "जादू" गुण, किसी भी है कि वास्तव में कोड अपने आप में प्रकट नहीं होते हैं, जिसका अर्थ है के लिए विशेष रूप और स्पष्ट रूप से है। यह मुख्य कारण है कि टैग केवल कक्षा डॉकब्लॉक में क्यों होता है। इस प्रकार, मैं उन आईडीई का अनुमान लगा रहा हूं जो "संपत्ति" टैग को "कोड में नहीं देखा गया" परिप्रेक्ष्य से ऐसा करते हैं। अनुमोदित, मैं एक उम्मीद को समझ सकता हूं कि स्वत: पूर्ण ऐसी संपत्ति के अस्तित्व को पहचान लेना चाहिए, और इसलिए इसे आपके लिए उपलब्ध कराएं। हालांकि, मेरी शर्त यह है कि आईडीई मॉडल बनाने के लिए केवल कोड का उपयोग करके चिपके रहेंगे, और केवल उन दस्तावेज़ों को पूरक करने के लिए डॉकब्लॉक जानकारी का उपयोग करें जो इसे कोड में पहले से देखे जा सकते हैं।

"var" टैग का उपयोग करना आपके "कोडेड" गुणों को दस्तावेज करने का एक उचित तरीका है। आप सभी गुण पर कि टैग का उपयोग करने के लिए आवश्यक लाइनों को कम करना चाहते हैं, एक पंक्ति docblock का उपयोग करें:

/** @var int */ 
public $id; 

इसके अलावा, आप docblocks, जहां टैग समानता को कम करने के docblock टेम्पलेट का उपयोग कर सकता है अपने कोड फिट बैठता है:

/** @var string */ 
public $name; 

/**#@+ @var int */ 
public $id; 
public $number; 
/**#@-*/ 

कि इस छोटे से सूची में काफी बचत की तरह प्रतीत नहीं होता है, लेकिन यह मदद करता है जब वहाँ गुण के बहुत सारे हैं। इसके अलावा, यह तरीकों के आसपास ठीक काम करता है।

Answer 2

मैं प्रत्येक संपत्ति के ऊपर @var का उपयोग करना पसंद करता हूं और कोई @property बिल्कुल नहीं। मुझे लगता है कि यह आपको उस चीज़ के साथ टिप्पणियों को अधिक निकटता से जोड़ने की अनुमति देता है जिस पर टिप्पणी की जा रही है। यानी, संपत्ति के लिए टिप्पणियां हमेशा संपत्ति के बगल में होती हैं। यदि आप @property शैली का उपयोग कर रहे हैं और आपके पास संपत्तियों के टन के साथ एक बड़ी कक्षा है, तो यह पूरी तरह से संभव है कि एक संपत्ति का वर्णन करने वाली टिप्पणी पृष्ठ से दूर है।

Answer 3

मुझे सटीक वाक्यविन्यास के बारे में निश्चित नहीं है लेकिन मुझे यकीन है कि नेटबीन मानक PHP दस्तावेज़ीकरण का पालन करेंगे।

http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.pkg.html http://www.phpdoc.org/