dotnet/roslyn

Make `path` a first-class citizen attribute of the `<inheritdoc />` tag

Open

#75.598 aperta il 23 ott 2024

Vedi su GitHub
 (7 commenti) (2 reazioni) (0 assegnatari)C# (4257 fork)batch import
Area-IDEhelp wanted

Metriche repository

Star
 (20.414 star)
Metriche merge PR
 (Merge medio 6g 17h) (256 PR mergiate in 30 g)

Descrizione

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:

  1. Make IntelliSense stop at <inheritdoc| />, prompting to select either cref or just nothing (in case there's a base class or interface to inherit from), omitting all attributes at once.
  2. If cref was selected, possibly prompt to assist with creating a valid value.
  3. Only if cref exists & is valid, prompt for path.
  4. If path was selected, prompt to assist with creating a valid XPath query string.
  5. After completion, move cursor past the closing angle bracket.

Part II (might be done in a separate issue - tell me & I happily create it):

  1. Make the <inheritdoc /> tag XML-compliant by inserting a whitespace before the slash (/).
  2. 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.

Guida contributor