Roslyn: Include XML doc comments when implementing an interface with Shift+Alt+F10

[kuhlenh]

[Filed on behalf of a customer]

Most of the the time the comments apply to the class implementing the interface, so it makes sense to just copy the comments over.

VS Feedback 456983

[dpoeschl]

Do we really want to always do this? Maybe just under an option?

[dpoeschl]

Can we instead show the first discovered inherited doc comments in QuickInfo/IntelliSense?

For example, quick info on D in this code:

``` C#
///

B1 says Hello, World

interface B1
{
}

///

Hello from B2!

interface B2 : B1
{
}

class D : B2
{
}

might look something like:

class D
From interface B2: Hello from B2!
```

/cc: @CyrusNajmabadi

[dpoeschl]

Can we re-triage this to decide whether duplicating the comments is really what we want, instead of the above suggestion or support for inheritdoc?

[Pilchie]

We agree that duplicating _isn't_ what we want. We think the ideal solution here is for the compiler to support inheritdoc. Barring that, it would be reasonable for the IDE to find the overridden/implemented member and use its doc implicitly.

[antonssonj]

Hi,
I’m thinking of grabbing this item, is it still up for grabs? It could save me some time implementing an internal API that uses a lot of IoC and has the compiler generating xml documentation files.

I have made some tests and think it could be implemented like this.

• Add inheritdocas a recommended tag to get completion when writing comments.
• Add a new property bool Inheritdoc to the DocumentationCommentType.
• In the extension method ISymbolExtensions.GetDocumentationComment check if the symbol has a <inheritdoc /> tag and find the overridden/implemented symbol and merge the DocumentationCommentof the parent symbol and the symbol.
• Update the Implement interface code action, not sure of the best way to do it. If CodeGenerateOptions.GenerateDocumentationComments is true there could be a check in TryGetDocumentationCommentto see if inheritdocis applicable but that feels like a hack and maybe there needs to be another flag in CodeGenerateOptions.

Alternative approaches:

• Just Implement bullet 3 above without the check for inheritdoc. It will only solve the problem with intellisens in VS. But another problem is that the compiler will generate a warning (CS1591) if the option XML documentation file is used.
• Instead of adding inheritdoc to the code actions maybe an analyser with a code fix would be enough. It would also help fixing a codebase where lots of comments are copied or empty. Where is the best place for an analyser like that?

Happy for feedback

[Pilchie]

Yes, it's still up for grabs, and we'd love it if you are interested in taking it on. @DustinCampbell, @dpoeschl, and I had a quick chat about how we think it might work this morning.

I'm going to assign the issue to @dpoeschl to work with you on the design. It's too late to include this in VS 2015 Update 2, but if things come together, we'd love to include it in the next VS Update after that!

[CyrusNajmabadi]

I personally don't think we need something like "inheritdoc".
I think that the IDE should just have a good experience around symbols that don't have doc comments on them. In that case, we simply go look and see if there's a doc comment on higher symbol. We then present this in the UI in a nice way. i.e. we say 'here's some doc comments. but they actually came from this other symbol."

[dpoeschl]

@CyrusNajmabadi We discussed the tooling ecosystem that makes a Roslyn implementation of inheritdoc useful offline earlier. We can _also_ create a great IDE experience for both cases with inheritdoc (which we would honor) and without (using a heuristic). inheritdoc would take precedence over the heuristic in the IDE. Does that dual approach to handle both existing tooling and improving IDE experiences with/without inheritdoc sound good to you?

[CyrusNajmabadi]

@dpoeschl Yup. That sounds good.

[antonssonj]

Great, so what’s the next step? Did your quick chat about how it might work differ a lot from my suggestion? Otherwise I could continue to work from my tests. I guess there will be a lot of details to discuss.

[antonssonj]

@dpoeschl I have expanded my tests and have implemented the most common cases. I have some thoughts that would be good to get some feedback on.

• This feature is pretty big, should it be divided in different Pull Requests?
  
  
  
  • Completion for the inheritdoc comment
  
  
  • An Analyser that fix CS1591, (Best way that I have found to fix the original issue)
  
  
  • Implementation of inheritdoc and heuristic in QuickInfo/IntelliSense.
  
  
• For inheritdoc in QuickInfo, do you think we should implement all features from Sandcastle? Is everything applicable for an implementation in VS like Inherit documentation from all base classes working backwards up the inheritance chain.

[rchande]

@dpoeschl What's the status of this?

[sharwell]

I think it would be good to treat this as blocked on dotnet/csharplang#313.

[binki]

https://developercommunity.visualstudio.com/content/idea/412325/.html was marked a duplicate of this.

[kendrahavens]

Closing this issue as complete. Starting in Visual Studio 2019 Update 16.4 methods that have no XML documentation can now automatically inherit XML documentation from the method it is overriding. Place your cursor over the undocumented method that implements a documented interface method. Quick Info will then display the XML documentation from the interface method. Release notes

[TobiasKnauss]

@kendrahavens you added a link to the release notes, but purely from reading them I wouldn't know that this issue was solved. Is there another "full" list of changes in a release?

[kendrahavens]

@TobiasKnauss Apologies for the delay. I should have mentioned in the comment and in the release notes that this does apply to classes and interfaces as well as overridden methods. You can find a sample on an interface using inheritdoc in our docs: https://docs.microsoft.com/en-us/dotnet/csharp/codedoc#inheritdoc

Is that what you were looking for?

[TobiasKnauss]

Yes, but I already found that. I just wanted to know whether the notification about inheritdoc was forgotten in the release notes or there were other, more detailed release notes.

[kendrahavens]

No, there were not other detailed release notes other than the overridden methods mentioned and the doc updates. I can update the release notes to include the inheritdoc tag example.

[chm-tm]

The release notes have been archived meanwhile.