APIv4 - Variable substution in docblocks

[colemanw]

Overview

Makes the help text more meaningful in the Api Explorer by always referring to the correct entity & action names.

Before

Lots of generic classes/functions meant lots of generic help text.

After

Replaces $ENTITY and $ACTION in docblocks to improve help text in the api explorer.

[civibot]

(Standard links)

• If this is your first pull-request for CiviCRM, please browse CONTRIBUTING.md for information about the development and testing processes.
• If you are reviewing this pull-request, you may wish to consult the test sites and the Review Standards (long template, short template).

[seamuslee001]

I think the test fail relates @colemanw

[colemanw]

Ok, the failing test is PartialSyntaxTest.testAllPartials

I haven't seen that one before, but it appears to take an html file, re-encode it with phpQuery and then compare the before/after to make sure they match. It ignores whitespace, so aside from that the diff shows that the re-encoded version drops closing slashes from self-closing elements. E.g. it changes

<input />

to

<input>

I looked it up and a lot of people have different opinions on which is correct. TL;DR - both formats are acceptable in HTML5.

I did a little more digging and the test appears to be ignoring those differences as well (the test strips closing slashes before comparing the before/after). That leaves just one difference that actually triggered the test failure. It changed this:

<li ng-repeat="ref in helpContent.see" ng-bind-html="ref"></li>

to this:

<li ng-repeat="ref in helpContent.see" ng-bind-html="ref">

Yikes, that looks completely wrong to me. li is not a void element so at the very least should get a self-closing slash at the end, but from what I've read, the original string is actually correct.
I've added a space in-between the opening and closing tag to see if that will get the test to pass, which kicks the can down the road on a messed-up test but would get this PR to pass.

[colemanw]

Ok that worked. Adding a space inside <li> </li> tricked phpQuery into thinking the element was not empty.
Doesn't solve the buggy test but at least this PR is good to go.