IBX-4929: ContentService: Fix @see usage

[adriendupuis]

Question	Answer
JIRA issue	IBX-4929
Type	improvement
Target Ibexa version	v4.0
BC breaks	yes/no

Fix @see usage for phpDocumentor 3.3.1

• The parenthesis are mandatory for the reference to be seen as a function.
• The className shouldn't but seems mandatory too.

Checklist:

• Provided PR description.
• Tested the solution manually.
• Provided automated test coverage.
• Checked that target branch is set correctly (main for features, the oldest supported for bugs).
• Ran PHP CS Fixer for new PHP code (use $ composer fix-cs).
• Asked for a review (ping @ibexa/engineering).

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
1 Code Smell

No Coverage information
0.0% Duplication

[alongosz]

The parenthesis are mandatory for the reference to be seen as a function.

This is bad. It's semantically wrong from the software engineering point of view. You're referencing a method, not its call. If there's no way to work around it, maybe we should drop this arcane tool?

[adriendupuis]

The parenthesis are mandatory for the reference to be seen as a function.

This is bad. It's semantically wrong from the software engineering point of view. You're referencing a method, not its call. If there's no way to work around it, maybe we should drop this arcane tool?

@alongosz, I agree with the semantic problem. The parenthesis are not part of the method name.

phpDocumentor use () to show that it's a method also in methods menu list.
It's a convention that can be observed elsewhere like on W3Schools (I'm not fan of this website but that's not the subject): https://www.w3schools.com/php/func_array_map.asp

From my POV, this ugly convention might come from PHP itself.
PHP doesn't see Class::method as a reference to a method and will look for a constant.
You can't write something like $m=MyClass::staticMethod; $m();.
But, you can stupidly write:

class Test
{
    public const sameName = 'constant';

    public static function sameName()
    {
        return func_get_args();
    }
}
var_dump(Test::sameName, Test::sameName('method'));
$v='Test::sameName';
var_dump(constant($v), $v('method'));

In this example, () could help to solve the homonymy and precise that the subject is the method, not the constant.

From my POV, this parenthesis convention is acceptable.

About alternatives to phpDocumentor, I haven't test much yet (there isn't much alternatives anyway).

• Doxygen is a nuclear power plant. It takes hours where other takes minutes but it has a beautiful output with inheritance diagrams (I guess they are the ones consuming time and could be disabled). Navigation in the documentation is not as simple as phpDocumentor. It doesn't use the () convention in tis output. It wrongly renders inline @see as a block @see and need the () in the input.
• ApiGen sadly doesn't render the @see while it has a interesting default layout. Navigation is less straight forward than phpDocumentor but a bit better than Doxygen. It doesn't use the () convention in its output.

I'm looking for others.

For now, phpDocumentor is the easiest to use with automation, the easiest to stylize, with a look & feel similar to the REST API Reference.

The decision has been overridden

[Steveb-p]

I agree with @alongosz about the semantic meaning, but given that it is our tool of choice and the "impact" of the change is minimal, I'm ok with it 😅

[webhdx]

@adriendupuis Since we've agreed to use phpDoc in the past we need to comply with its syntax and not argue wether it's correct or not. I believe we may have issues like this in many more places.

[alongosz]

From my POV, this ugly convention might come from PHP itself.
PHP doesn't see Class::method as a reference to a method and will look for a constant.
You can't write something like $m=MyClass::staticMethod; $m();.

This is very good argument 👍

[alongosz]

Thank you @adriendupuis 🎉