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.

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?