Add guideline about annotation using one-line

[LukasReschke]

From owncloud/core#12279 (comment)

Opinions:

• @blizzz: 1 use-statement/relative
• @butonic: 1 use-statement - switch to @type as PSR5
• @Raydiation: 1 use-statement - switch to @type as PSR5
• @icewind1991: 3 full qualified
• @LukasReschke: 1 full qualified 1 use-statement - switch to @type as PSR5
• @MorrisJobke: 1 full qualified 1 use-statement - switch to @type as PSR5
• @nickvergessen: 1 line

[LukasReschke]

Summoning some other core devs:

@icewind1991 @schiesbn @butonic @georgehrke @blizzz @tomneedham @bantu @PVince81 @MorrisJobke @th3fallen (Hope I missed no-one that might be interested as well!)

Reason for that is that currently some annotate the type using three-line comments, others one-liners and then again others don't do it at all.

For the sake of Vertical Density I'd suggest that we use single line comments instead of bloating too much comments into it.

[LukasReschke]

Please notice that PHPStorm can generate such member variables annotations on it's own just by typing /** one line above the variable.

[icewind1991]

My preference goes out to the three line variant.

Additionally a note about using the fully qualified name versus just the classname would be useful (\OC\Foo\Bar vs Bar), phpstorm defaults to the later I prefer the former

[MorrisJobke]

One line full qualified nane

[butonic]

My vote is one line, class name only.

The full qualified type is resolved via the use statement, no need to duplicate.

PSR5 states that @var is deprecated for properties and @type should be used instead. phpStorm 8.0+ can be configured to use one line as well as full-qualified types: https://www.jetbrains.com/phpstorm/webhelp/creating-php-documentation-comments.html

Method body comments for variables still use @vareg :

    /**
     * @param Node[] $nodes
     * @param \OC_EventSource $eventSource
     */
    public function doSth (array $nodes, \OC_EventSource $eventSource = null) {
        foreach ($nodes as $node) {
            $node->...      // codehinting works
        }
        /* or */
        if (isset($nodes[0])) {         
            /** @var File */
            $file = $nodes[0];
            $file->...          // codehinting works
        }
        /* ... */
    }

[blizzz]

/me votes for one-line and relative name

[icewind1991]

My argument for FQN is that it provides the full information in one place, with relative names I need to look at both the current namespace and use statements before I know what class is being referenced

[nickvergessen]

1line, dont care about full/use as long as the use is present and therefor the methods are found

[BernhardPosselt]

Same opinion as @butonic

[DeepDiver1975]

I honestly don't care - as long as my IDE can handle it 🙈

Generally speaking: following PSR is desired.

[MorrisJobke]

If there is a PSR for that -> use that

[BernhardPosselt]

Probably bad idea to use a private namespace class

[nickvergessen]

woot? This is just to point out how doc blocks should look like

[BernhardPosselt]

Yep ;)

[BernhardPosselt]

👍

[carlaschroder]

@LukasReschke Is this ready to merge?

[jospoortvliet]

@LukasReschke ping?

[carlaschroder]

@LukasReschke Any reason to keep this open?

[MorrisJobke]

@LukasReschke Can we just merge it with the use-statement?