Addresses the issue reported in #506, but not with the reported syntax, but instead the one actually originally documented.
The reported syntax did piggy-back on exiting id-based linking: [text][@:api(foo.Bar)].
But the reported undesired lower-case transformation of the type name is based on the fact that link ids are normalized early and deferring that step comes with a high risk of regressions for standard links.
Instead this PR implements custom link texts for link directives based on the literal URL syntax of native text markup as these do not undergo any transformations before rendering: [text](@:api(foo.Bar)). The syntax is not ideal, due to the double closing parenthesis, but it's the most robust option for now for a feature that is not heavily used.
The third option, using standard directive syntax with nested bodies @:api(foo.Bar) link text @:@ had to be discarded due to the fact that directives do not support optional bodies for avoiding potentially significant parsing inefficiencies. The only way this syntax could be supported would be with different directive names for links with and without custom link text which feels even less intuitive than the approach chosen now.
Addresses the issue reported in #506, but not with the reported syntax, but instead the one actually originally documented.
The reported syntax did piggy-back on exiting id-based linking:
[text][@:api(foo.Bar)]. But the reported undesired lower-case transformation of the type name is based on the fact that link ids are normalized early and deferring that step comes with a high risk of regressions for standard links.Instead this PR implements custom link texts for link directives based on the literal URL syntax of native text markup as these do not undergo any transformations before rendering:
[text](@:api(foo.Bar)). The syntax is not ideal, due to the double closing parenthesis, but it's the most robust option for now for a feature that is not heavily used.The third option, using standard directive syntax with nested bodies
@:api(foo.Bar) link text @:@had to be discarded due to the fact that directives do not support optional bodies for avoiding potentially significant parsing inefficiencies. The only way this syntax could be supported would be with different directive names for links with and without custom link text which feels even less intuitive than the approach chosen now.Closes #506.