[TYPO3-team-core-v5] Rules for variable/property documentation in code

[Karsten Dambekalns]

Hi folks,

I am currently working on persistence stuff, and for that I will make use of @var annotations. Thus it becomes even more important to document your "member variables" (or rather "properties") correctly.

Now what does correctly mean? I looked at our current code as well as the phpDocumentor manual, and it seems this is correct

/**
 * @var string This is some description
 */

I then noticed that PDT in Eclipse only detects the description if this is written in two lines:

/**
 * This is some description
 * @var string
 */

To make sure this doesn't break phpdoc I ran some changed files through it, and it turns out even phpPocumentor likes this better: Instead of showing the variable type *and* the @var tag, it only displays the type (and the description as expected).

So, if noone objects we will use this from now on and gradually upgrade old code as we touch it. This is your chance to check the behaviour of your IDE of choice and report results if this makes or breaks things for you.

Karsten

PS: Making sure there is only a type and no description after the @var annotation makes life easier for me as well. :)
-- 
I'm trying a new usenet client for Mac, Nemo OS X.
You can download it at http://www.malcom-mac.com/nemo