Skip to content

Add missing XML documentation to public APIs #7788

Open

Description

@svick

Goal

Add missing XML documentation to public APIs, including publicly accessible protected members, so that IntelliSense and generated API reference documentation cover the API surface.

Basic inventory

A diagnostic build at commit 272f2fb found 6,459 distinct types/members missing XML documentation in 34 projects, plus 238 additional undocumented members suppressed by source-level pragmas.

Stable-version projects (1.x and later)

Project Missing XML documentation
Microsoft.ML.Data 108
Microsoft.ML.Transforms 73
Microsoft.ML.TimeSeries 44
Microsoft.ML.Core 41
Microsoft.ML.StandardTrainers 34
Microsoft.ML.DataView 32
Microsoft.ML.LightGbm 29
Microsoft.ML.ImageAnalytics 28
Microsoft.ML.FastTree 18
Microsoft.ML.OnnxTransformer 17
Microsoft.ML.Vision 13
Microsoft.ML.KMeansClustering 5
Microsoft.ML.Mkl.Components 5
Microsoft.ML.PCA 5
Microsoft.ML.TensorFlow 3
Microsoft.Extensions.ML 2
Microsoft.ML.Tokenizers 1
Total 458

Pre-1.0 projects (0.x)

Project Missing XML documentation
Microsoft.Data.Analysis 5,153
Microsoft.ML.AutoML 371
Microsoft.ML.Sweeper 228
Microsoft.ML.TorchSharp 110
Microsoft.ML.Fairlearn 40
Microsoft.ML.ResultProcessor 31
Microsoft.ML.SamplesUtils 28
Microsoft.ML.AutoML.Interactive 16
Microsoft.Data.Analysis.Interactive 5
Microsoft.ML.CodeGenerator 5
Microsoft.ML.Maml 4
Microsoft.ML.Console 2
Microsoft.ML.DnnAnalyzer 2
Microsoft.ML.Experimental 2
Microsoft.ML.Recommender 2
Microsoft.ML.OneDal 1
Microsoft.ML.OnnxConverter 1
Total 6,001

Main concentrations and examples

  • Data.Analysis: 4,898 of its 5,153 gaps are in two T4-generated files: PrimitiveDataFrameColumn.BinaryOperationAPIs.ExplodedColumns.cs (3,151) and PrimitiveDataFrameColumn.BinaryOperators.cs (1,747). Update the corresponding .tt templates and regenerate their outputs rather than hand-editing generated files.
  • Source-level suppression: another 238 distinct Data.Analysis members are missing documentation in DataFrame.BinaryOperators.cs and DataFrameColumn.BinaryOperators.cs, where #pragma warning disable 1591 remains active. These are not included in the tables.
  • AutoML: 227 of its 371 gaps are in source-generator output; these should be addressed in the generator.
  • Ordinary API gaps: examples include AutoMLExperiment's constructor and SetTrainingTimeInSeconds, DataViewRowId.CompareTo and Equals(DataViewRowId), and the span-based BertTokenizer.CreateTokenTypeIdsFromSequences overload. The last example is the only gap found in Tokenizers.

Incremental enforcement

CS1591 could be enabled in an individual project once all of its APIs are documented, without waiting for the entire repository to be clean.

For each completed project, remove its effective CS1591 suppression, including the suppression inherited from src/Directory.Build.props and any project-specific or source-level suppressions. Once clean, also remove CS1591 from its effective WarningsNotAsErrors so that the existing warnings-as-errors policy prevents new documentation gaps. This should be done selectively for completed projects while unfinished projects retain their suppressions.

Activity

  1. github-actions commented on Oct 13, 2026

    @github-actions
    Contributor

    🔍 No similar issues found with high confidence.


    AI-powered similar issue detection

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    untriagedNew issue has not been triaged

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions