Make `path` a first-class citizen attribute of the `<inheritdoc />` tag
#75,598 opened on Oct 23, 2024
Repository metrics
- Stars
- (20,414 stars)
- PR merge metrics
- (Avg merge 6d 17h) (256 merged PRs in 30d)
Description
Summary
Much like #75597, offer path attribute for selection in IntelliSense & ideally assist in building the XPath query string, e.g., after typing <inheritdoc cref="string.Join(char,string[])" path="/|" /> (Note: | marks cursor's spot), IntelliSense should offer summary, param, returns, etc. for completion.
Afterwards, e.g., in case of param (<inheritdoc cref="string.Join(char,string[])" path="/param[|]" />), it should offer, separator & value, too.
Background and Motivation
Offer proper completion help for XML Doc users - every developer loves proper docs, so VS should do its very best to help us developers with writing docs.
For example, I discovered the possibility of using the path attribute by a literal accident.
It's a real pity that the huge power of XML Doc isn't advertised more - throughout Visual Studio, but also within the XML Docs themselves - e.g., inheritdoc mentions the path attribute, but doesn't even give a single example.
Proposed Feature
Part I:
- Make IntelliSense stop at
<inheritdoc| />, prompting to select eithercrefor just nothing (in case there's a base class or interface to inherit from), omitting all attributes at once. - If
crefwas selected, possibly prompt to assist with creating a valid value. - Only if
crefexists & is valid, prompt forpath. - If
pathwas selected, prompt to assist with creating a valid XPath query string. - After completion, move cursor past the closing angle bracket.
Part II (might be done in a separate issue - tell me & I happily create it):
- Make the
<inheritdoc />tag XML-compliant by inserting a whitespace before the slash (/). - Extend this to any self-closing / standalone XML Doc tag, i.e.,
<include />,<see />&<seealso />, too.
Alternative Designs
Fiddling around with manual XPath syntax & loads (!) of trial & error regarding what's possible inside VS & what's not.