System.Speech is missing API documentation

[ViktorHofer]

See #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]

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

Issue Details

---

See #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]

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

[ViktorHofer]

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:

• Microsoft.Extensions.DependencyInjection.Specification.Tests is missing API documentation #87709
• System.Numerics.Tensors is missing API documentation #87710

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: #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 73e4061, the library's now fully documented and the compiler verifies that and would otherwise emit a CS1591 error.

[ViktorHofer]

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

• Microsoft.Bcl.AsyncInterfaces
• Microsoft.Bcl.Cryptography
• Microsoft.Bcl.TimeProvider
• Microsoft.Extensions.DependencyInjection.Specification.Tests
• Microsoft.Extensions.Diagnostics
• Microsoft.Extensions.Diagnostics.Abstractions
• Microsoft.Extensions.Hosting.Systemd
• Microsoft.Extensions.Hosting.WindowsServices
• Microsoft.NET.WebAssembly.Webcil
• Microsoft.VisualBasic
• System
• System.AppContext
• System.Buffers
• System.ComponentModel.DataAnnotations
• System.Configuration
• System.Core
• System.Data
• System.Data.DataSetExtensions
• System.Diagnostics.Debug
• System.Diagnostics.EventLog.Messages
• System.Diagnostics.Tools
• System.Drawing
• System.Dynamic.Runtime
• System.Formats.Cbor
• System.Globalization
• System.Globalization.Calendars
• System.Globalization.Extensions
• System.IO
• System.IO.Compression.FileSystem
• System.IO.FileSystem
• System.IO.FileSystem.Primitives
• System.IO.UnmanagedMemoryStream
• System.Net
• System.Numerics
• System.Numerics.Tensors
• System.Reflection
• System.Reflection.Extensions
• System.Resources.Reader
• System.Resources.ResourceManager
• System.Runtime.CompilerServices.Unsafe
• System.Runtime.Extensions
• System.Runtime.Handles
• System.Runtime.InteropServices.RuntimeInformation
• System.Runtime.Serialization
• System.Runtime.Serialization.Schema
• System.Security
• System.Security.Cryptography.Algorithms
• System.Security.Cryptography.Cng
• System.Security.Cryptography.Csp
• System.Security.Cryptography.Encoding
• System.Security.Cryptography.OpenSsl
• System.Security.Cryptography.Primitives
• System.Security.Cryptography.X509Certificates
• System.Security.Principal
• System.Security.SecureString
• System.ServiceModel.Web
• System.ServiceProcess
• System.Speech
• System.Text.Encoding
• System.Threading.RateLimiting
• System.Threading.Tasks
• System.Threading.Tasks.Extensions
• System.Threading.Timer
• System.Transactions
• System.ValueTuple
• System.Web
• System.Windows
• System.Xml
• System.Xml.Linq
• System.Xml.Serialization
• System.Xml.XmlDocument
• WindowsBase
• Microsoft.XmlSerializer.Generator
• mscorlib
• netstandard

[stephentoub]

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]

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]

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

[carlossanlop]

Step 1: Finish documenting all APIs in System.Speech in dotnet-api-docs. Only 4 APIs were incomplete. I have a PR for that: dotnet/dotnet-api-docs#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]

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).

[ericstj]

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.