search

dotnet / runtime

.NET is a cross-platform runtime for cloud, mobile, desktop, and IoT apps.
https://docs.microsoft.com/dotnet/core/
MIT License
14.98k stars 4.66k forks source link

System.Speech is missing API documentation #87711

Open ViktorHofer opened 1 year ago

ViktorHofer commented 1 year ago

See https://github.com/dotnet/runtime/pull/84917 for more context.

The compiler generated XML file for System.Speech is shipping to customers via the nuget package and is missing public API documentation. The above linked PR disables the compiler error CS1591 until all the API is documented.

When working on this, remove the NoWarn=1591 setting from the project file.

ghost commented 1 year ago

Tagging subscribers to this area: @dotnet/area-system-speech See info in area-owners.md if you want to be subscribed.

Issue Details
See https://github.com/dotnet/runtime/pull/84917 for more context. The compiler generated XML file for System.Speech is shipping to customers via the nuget package and is missing public API documentation. The above linked PR disables the compiler error CS1591 until all the API is documented. When working on this, remove the NoWarn=1591 setting from the project file.
Author: ViktorHofer
Assignees: -
Labels: `area-System.Speech`
Milestone: -
stephentoub commented 1 year ago

I'm surprised we're shipping the compiler-generated XML file rather than one derived from the docs.

ViktorHofer commented 1 year ago

I'm surprised we're shipping the compiler-generated XML file rather than one derived from the docs.

The docs package (Microsoft.Private.Intellisense.nupkg) doesn't provide an XML file for System.Speech, nor does it for a couple of other assemblies today:

Instead of getting a documentation file added to the package (which presumably would be work for the docs team), we prefer to have the source-of-truth in runtime: https://github.com/dotnet/runtime/issues/44969. @carlossanlop and Akhil were working on porting tool that should ease that process.

In the case of System.Threading.RateLimiting, it was already largely in-source documented and there is no XML file provided by the docs team either. With https://github.com/dotnet/runtime/commit/73e40617a0333d5829c12cc64503d586a708fcd3, the library's now fully documented and the compiler verifies that and would otherwise emit a CS1591 error.

ViktorHofer commented 1 year ago

FWIW these are all the current docs source-of-truth assemblies in runtime (please ignore all the pure facade assemblies):

stephentoub commented 1 year ago

we prefer to have the source-of-truth in runtime

Yes, but it's not for Speech, as is evidenced by this issue and the fact that the docs are more complete than the xml comments.

ericstj commented 1 year ago

This is happening because the Microsoft.Private.Intellisense package is missing System.Speech. @carlossanlop any idea how we can get that added? Alternatively we can just run porting tool on the .NETFramework XMLs to get it ported to source. System.Speech.zip

ericstj commented 1 year ago

@carlossanlop - can you see about getting this added to the intellisense package?

carlossanlop commented 12 months ago

Step 1: Finish documenting all APIs in System.Speech in dotnet-api-docs. Only 4 APIs were incomplete. I have a PR for that: https://github.com/dotnet/dotnet-api-docs/pull/9336

Step 2: Understand why there's no System.Speech assembly in the ref assemblies drop that we generate for dotnet-api-docs. The item exists in Versions.props and Versions.Details.xml of api-catalog-infra, but the assembly file is not getting published in the ref assemblies drop when we build, so there are no docs for that assembly included in the the Microsoft.Private.Intellisense package.

Step 3: Once figured out the root cause, send an updated ref-assemblies drop to dotnet-api-docs, then generate a new Microsoft.Private.Intellisense version, confirm it contains an xml for System.Speech, and finally confirm it works for customers in intellisense.

Step 4 (Future): When the PNSE problem is fixed, backport all the docs of System.Speech from dotnet-api-docs using the PortToTripleSlash tool and re-enable the property in the csproj so that triple slash docs become the source of truth for this assembly.

ViktorHofer commented 12 months ago

Step 2: Understand why there's no System.Speech assembly in the ref assemblies drop that we generate for dotnet-api-docs. The item exists in Versions.props and Versions.Details.xml of api-catalog-infra, but the assembly file is not getting published in the ref assemblies drop when we build, so there are no docs for that assembly included in the the Microsoft.Private.Intellisense package.

The reference assembly is part of the Microsoft.DotNet.Runtime.Docs.Transport package. Shouldn't we use that instead for runtime and aspnetcore (those are the repos that already publish a transport docs package).

image
ericstj commented 12 months ago

Just chiming in that I think this is the reason for step 2: https://github.com/dotnet/api-catalog-infra/pull/73 Agree with @ViktorHofer that if we created new transport packages to eliminate some of the complexity in api-catalog-infra using that seems preferrable.

Also, for Step 4, we're still blocked because this assembly has a RID-specific impl with PNSE. I considered doing porting the docs to fix this package but did not for this reason.