dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
4.07k stars 865 forks source link

[Feature Request] Add closing parenthesis ')' as a punctation sign marking the end of the shorthand form of cross reference UID #8439

Open GlmGb opened 1 year ago

GlmGb commented 1 year ago

I often put UIDs of my API object in shorthand form in parenthesis, either to link to the object that the current sentence refers to, or to give examples: Ex. "this functionality is related to entities that support this feature (@Namespace1.Myobject1 and @Namespace1.Myobject2)"

But since ')' is not a valid punctuation to mark the end of the UI, only @Namespace1.Myobject1 will be converted to a link to the matching object in API documentation, but @Namespace1.Myobject2 is left "as is": "this functionality is related to entities that support this feature (Myobject1 and @Namespace1.Myobject2)"

The current workaround is to have an extra space ' ' before the closing parenthesis, or use the more complicated markdown syntax, but it is neither intuitive nor elegant.

I expect a closing parenthesis to be considered as a sign that marks the end of a UID (like [.,;:!?`~]), in the context where this closing parenthesis has no other function than a standard text sign.

KalleOlaviNiemitalo commented 1 year ago

The @"Namespace.Myobject" syntax with quotation marks isn't very intrusive.

Does @System.Object.Equals(System.Object) work now? If it does, it should be kept working. Perhaps the parser could count opening and closing parentheses.

GlmGb commented 1 year ago

Yes, @System.Object.Equals(System.Object) works as expected, but as you mentioned, the closing parenthesis is in this case part of the UID, the parser is able to know it since there is a matching opening parenthesis after the '@'.

yufeih commented 1 year ago

Does quote work (@"Namespace1.Myobject1" and @"Namespace1.Myobject2")?