Documentation fix - for inline refs use @link instead of @see

[jrsupplee]

Inline references in documentation should use {@link ...} not {@see ...}

[Srokap]

FYI we adopted stronger commit standards and that's why your PR is failing tests. Please follow them in future as that allows us automating release process: #5976

I'll fix this one for you this time. I also wonder if you searched whole codebase for the problems or just some part of it? It would be best to get rid of them in one push. Other than that LGTM.

[ewinslow]

This is great. Just so we're clear, what is the difference between these two annotations? Something explicit in the commit message like @see doesn't actually create links between the documentation. @link is the correct annotation and results in working links. Did I get that right?

[jrsupplee]

I searched the whole codebase for {@see and these were all that I found.

@see does generate links but it creates messy and confusing documentation as it starts the 'See ...' on a new line.

[mrclay]

I don't think this is right. The phpDoc docs says @link is only for expressing relationships with URLs, not structural elements. I'd prefer to get the semantics rather than worry about presentation for now.

[Srokap]

Have a look here: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.link.pkg.html

In examples they use @link to reference class name, not always URL

Unless linking to an element, @link assumes the arguments passed are fully-formed URLs. 
Generally speaking, if you want to link to an element's documentation, use @see 
or inline {@link}... you can use @link, but the other options are better.

[ewinslow]

OK glad I asked for clarification.

So @see is not a valid inline annotation. It creates blocks which looks funny when used inline. @link results in the intended inline reference to the relevant element.

[Srokap]

I've found few more cases of See starting with capital letter. Added to the commit in #6881

Closing this one.

[Srokap]

Merged in 50b0e39, thanks @jrsupplee