Add remarks and examples to Windows AI API reference docs#123
Draft
GrantMeStrength wants to merge 6 commits into
Draft
Add remarks and examples to Windows AI API reference docs#123GrantMeStrength wants to merge 6 commits into
GrantMeStrength wants to merge 6 commits into
Conversation
Fill in empty -remarks, -see-also, and -examples sections for 16 class-level API reference files across Microsoft.Windows.AI.Text and Microsoft.Windows.AI.Imaging namespaces. AI.Text classes updated: - LanguageModel: Phi Silica integration, availability check pattern, IDisposable, NPU requirement, China restriction, code example - TextSummarizer: Text Intelligence Skill, three summarization methods - TextRewriter: tone options, rewriting behavior - TextToTableConverter: structured table output - ConversationItem: message/participant properties, conversation summary usage - ConversationSummaryOptions: configuration for conversation summarization - LanguageModelOptions: content filtering configuration - LanguageModelResponseResult: status checking and error handling AI.Imaging classes updated: - TextRecognizer: enhanced OCR description, NPU acceleration, legacy comparison - ImageScaler: Image Super Resolution, 8x scaling, MaxSupportedScaleFactor - ImageObjectExtractor: object segmentation with hints - ImageObjectRemover: object erasure workflow with mask - ImageDescriptionGenerator: natural-language descriptions, description kinds - ImageObjectExtractorHint: include/exclude points and rects - RecognizedText: result container, Lines property - RecognizedLine: text, words, style, confidence Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Phase 2: Fill in -remarks, -see-also, and -examples for 36 method-level API reference files across Microsoft.Windows.AI.Text and Microsoft.Windows.AI.Imaging namespaces. LanguageModel methods (10 files): - CreateAsync, EnsureReadyAsync, GetReadyState: availability check pattern - GenerateResponseAsync (3 overloads): token streaming, status checking, context window usage, content moderation, code example - GenerateResponseFromEmbeddingsAsync (3 overloads): RAG scenarios - Close: IDisposable guidance Text Intelligence Skills (9 files): - TextSummarizer: SummarizeAsync (with example), SummarizeConversationAsync, SummarizeParagraphAsync, constructor - TextRewriter: RewriteAsync (2 overloads), constructor - TextToTableConverter: ConvertAsync, constructor Imaging methods (17 files): - TextRecognizer: CreateAsync, EnsureReadyAsync, GetReadyState, RecognizeTextFromImage (ImageBuffer creation, result structure), RecognizeTextFromImageAsync - ImageScaler: CreateAsync, EnsureReadyAsync, GetReadyState, MaxSupportedScaleFactor - ImageDescriptionGenerator: CreateAsync, EnsureReadyAsync, GetReadyState, DescribeAsync (description kinds, content filtering) - ImageDescriptionKind: usage guidance for each enum value - ImageObjectRemover: CreateAsync, EnsureReadyAsync, GetReadyState Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR enriches the Windows AI WinRT API reference documentation by adding substantive -remarks, -see-also, and (in a couple of cases) -examples sections to 16 class-level pages across Microsoft.Windows.AI.Text and Microsoft.Windows.AI.Imaging, improving discoverability and usage guidance for Phi Silica, OCR, and imaging features.
Changes:
- Added detailed remarks/see-also guidance for Text Intelligence skill classes (summarize/rewrite/text-to-table) and supporting types.
- Added usage guidance for readiness checks / model setup, NPU/on-device behavior, and regional availability notes.
- Added/expanded C# examples for key entry points (notably
LanguageModelandTextSummarizer).
Reviewed changes
Copilot reviewed 52 out of 52 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| microsoft.windows.ai.text/texttotableconverter.md | Added remarks/see-also describing converting text into structured rows/columns and linking related types. |
| microsoft.windows.ai.text/textsummarizer.md | Added remarks/see-also plus a basic C# summarization example and method overview. |
| microsoft.windows.ai.text/textrewriter.md | Expanded remarks/see-also describing rewriting behavior and tone options. |
| microsoft.windows.ai.text/languagemodelresponseresult.md | Added remarks/see-also explaining status handling and diagnostic patterns. |
| microsoft.windows.ai.text/languagemodeloptions.md | Added remarks/see-also for configuring model behavior and content filtering. |
| microsoft.windows.ai.text/languagemodel.md | Added detailed remarks/see-also and a C# example covering availability and response generation. |
| microsoft.windows.ai.text/conversationsummaryoptions.md | Added remarks describing how options affect conversation summarization output. |
| microsoft.windows.ai.text/conversationitem.md | Added remarks/see-also clarifying role in conversation summarization input. |
| microsoft.windows.ai.imaging/textrecognizer.md | Expanded remarks describing OCR usage, readiness pattern, and output types. |
| microsoft.windows.ai.imaging/recognizedtext.md | Added remarks describing the OCR result container and navigation via lines/words. |
| microsoft.windows.ai.imaging/recognizedline.md | Added remarks describing line-level OCR data (text/words/style/confidence). |
| microsoft.windows.ai.imaging/imagescaler.md | Added remarks describing super resolution scaling, readiness, disposal, and max scaling factor. |
| microsoft.windows.ai.imaging/imageobjectremover.md | Added remarks describing object removal workflow including mask generation and removal methods. |
| microsoft.windows.ai.imaging/imageobjectextractorhint.md | Added remarks explaining include/exclude hint usage for segmentation guidance. |
| microsoft.windows.ai.imaging/imageobjectextractor.md | Added remarks describing segmentation workflow, factory methods, and mask retrieval. |
| microsoft.windows.ai.imaging/imagedescriptiongenerator.md | Added remarks describing description generation workflow, readiness, and result shape. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Use AIFeatureReadyState.Ready (not fabricated NotReady) in code examples - Fix broken markdown link for RecognizeTextFromImageAsync in recognizedtext.md - Fix incorrect filename suffix for RemoveFromSoftwareBitmap link Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Address Copilot review comments and audit findings: - Replace all NotReady enum references with EnsureNeeded or != Ready (AIFeatureReadyState has Ready, EnsureNeeded, NotSupportedOnCurrentSystem, DisabledByUser — no NotReady value) - Fix ContentFilterOptions link: contentsafety → contentmoderation - Fix ImageBuffer method name: remove fabricated CreateForSoftwareBitmap, use verified CreateBufferAttachedToBitmap / CreateCopyFromBitmap - Remove unverifiable 'up to 8x' scaling claim from MaxSupportedScaleFactor - Remove unverifiable 'between 0 and 1' progress range claim - Remove unverifiable 'handwritten vs. printed' style claim - Soften SummarizeParagraphAsync vs SummarizeAsync comparison - Soften RAG scenario claim on GenerateResponseFromEmbeddingsAsync - Add using Microsoft.Windows.AI.Text namespace imports to all code examples Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
GrantMeStrength
requested review from
Copilot
and removed request for
hamza-usmani
- Fix 'lanugage' → 'language' typo in 3 files - Add result.Status check before accessing result.Text in summarizer examples - Handle NotSupportedOnCurrentSystem/DisabledByUser states separately from EnsureNeeded in availability check examples Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Remove 'between 0 and 1' progress range (unverifiable) - Remove 'up to 8x' scaling claim, point to MaxSupportedScaleFactor instead - Remove 'handwritten or printed' — only Handwritten enum value exists - Remove SummarizeAsync 'key points' comparison (unverifiable) - Add status check to LanguageModel example Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Questions for SME reviewers
The following questions came up during authoring. Accurate answers would directly improve the docs — and are especially important for AI coding assistants (e.g. GitHub Copilot) that use API reference to generate code.
LanguageModel / Text APIs
doubleprogress value onEnsureReadyAsync: is it 0.0–1.0 or 0–100? We removed a "between 0 and 1" claim because we could not verify it.stringprogress onGenerateResponseAsync: is each progress callback a single new token, or the cumulative response so far? This is critical for implementing streaming UI.CreateAsyncwhenGetReadyState()returnsEnsureNeededorDisabledByUser? Does it throw, return null, or silently fail?SummarizeAsyncreturn bullet-point key points whileSummarizeParagraphAsyncreturns prose? We softened this claim because the signatures both returnLanguageModelResponseResult.PromptLargerThanContext.LanguageModeland the Text Intelligence Skill classes be used from background threads, or must they be called on the UI/dispatcher thread?Imaging APIs
ImageBufferfactory methods should developers use to convert aSoftwareBitmap? We verifiedCreateBufferAttachedToBitmapandCreateCopyFromBitmapexist but are unsure which is preferred and whether there are C++/WinRT-specific variants.RecognizedLineStyleenum only documentsHandwritten. Is there aPrintedorUnknownvalue, or is the absence ofHandwrittenthe indicator for printed text?RemoveFromSoftwareBitmap/RemoveFromImageBuffermodify the source in place or return a new image? The signatures suggest a return value, but the docs should be explicit.General
LanguageModelResponseResult.Status, should developers also catch specific exception types? If so, which ones?Summary
Adds remarks, see-also, and examples to 52 API reference files across
Microsoft.Windows.AI.TextandMicrosoft.Windows.AI.Imagingnamespaces. These are GA APIs (Windows App SDK 1.7+) that power Phi Silica, text recognition, and imaging features.Changes
Phase 1: Class-level files (16 files)
Microsoft.Windows.AI.Text (8 files)
Microsoft.Windows.AI.Imaging (8 files)
Phase 2: Key method files (36 files)
Motivation
OGF quality scan identified 93 files in these namespaces with empty remarks/examples. This PR addresses the highest-impact class and method files. All claims were audited against API metadata to avoid fabrication — the questions above flag areas where we intentionally left information out rather than risk inaccuracy.