Runtime: XML Documentation comments not included

[sgtfrankieboy]

I was looking through the recently added Regex code and noticed that a lot of XML documentation summaries are not there, but they do show up in the .NET Framework documentation.

Are the comments stored in an external file? If so, isn't it better to include them in the code or provide the external files? Some people would like to compile the libraries themselves and they would be missing a lot of inline documentation.

Example
_.NET Framework_

_.NET Core_

[weshaggard]

Yes a lot of the documentation is currently not part of the code, they are in a documentation database. We have plans to get them pulled from the doc database and inserted inline as xml doc comments in the code, we just haven't been able to do that work yet. We can use your issue he to track that work item.

[tarekgh]

@richlander @weshaggard do we have any plan yet for this issue?

[weshaggard]

@mairaw might have more information on this front, I don't know what the current thinking is.

[tarekgh]

@mairaw could you please advise what is the plan for this?

[mairaw]

We're working on the solution to document the .NET API reference. Since we couldn't use xml doc comments consistently across all the .NET source code, we'll have a solution that is somewhat similar to what we have today internally but that will be open source. From there, we'll also be generating the IntelliSense files.
Once we have the solution in place, we can work on updating the contributing guide to make sure users know what to do when they find issues with the API descriptions in the source code, docs site, IntelliSense, etc.

We need to sync with the dev team what would be the plan for porting those back to the source code though, if that's desired.

However, where is that comment coming from? When I look at the .NET Framework source, I don't see those comments as in the screenshot. Is that showing the IntelliSense for the .NET Framework?

/cc @bradygaster @karelz @dend

[karelz]

@mairaw we just had the same question in a dupe https://github.com/dotnet/coreclr/issues/10570 ... just curious if you are tracking the work somewhere in docs repo and what is the latest plan (or whom we should bug) ;-)
Thanks!

cc @orthros

[mairaw]

The issues are related but not quite the same IMO. There are a few efforts going on related to documentation.

For https://github.com/dotnet/coreclr/issues/10570: the community will able to contribute to the API reference docs soon which is what we use to generate the IntelliSense files. IntelliSense for the .NET Framework is not generated from source as a lot of people imagine.

For generating IntelliSense for the different .NET platforms: it's something we have in the backlog that we need to look at soon. We're moving to a new build system and tooling, so all functions need to be rebuilt and tested.

Now, we need to decide if we're going to backport the content from our docs to the source code. I don't think we've ever made a decision on that. For people compiling the libraries, wouldn't they need the /// comments in the source? Or having the IntelliSense would be enough?

The PM for .NET Reference is @dend.

[karelz]

Thanks for update.

Unless we can keep both way mirror between docs repo and CoreFX/CoreCLR, we should keep docs repo as the primary source of documentation and we should IMO not push the content into /// comments in CoreFX. I am not aware of any advantage of having such /// comments in source code (i.e. no value), especially if we don't take contributions to them, or worse when contributions to /// don't automatically mirror into IntelliSense built from docs repo (it will just confuse contributors and set false expectations).

IMO it is fine (albeit not ideal) to ask contributors to edit docs in docs repo.

[Petermarcu]

@mairaw @weshaggard didn't this get addressed in 2.0?

[mairaw]

It should have been @PeterMarcu. I haven't tested this though. Have you @weshaggard? Some classes will be missing IntelliSense though since we haven't reached 100% coverage for .NET Core yet. But classes that existed previously in the Framework should have IntelliSense now.

[weshaggard]

@Petermarcu which part of this issue are you referring to? If you are referring to getting updated intellisense then yes we did do that before 2.0 shipped. However if you are referring to consuming the doc comments in code or putting the docs into doc comments then no we haven't done that and I don't think we plan to do that.

[Petermarcu]

High level question is whether we need to track anything else here or should we close this issue?

[weshaggard]

I think we can close this as we have updated intellisense.