Add remarks and examples to Windows AI API reference docs

microsoft.windows.ai.imaging/imagedescriptiongenerator.md

@@ -15,6 +15,14 @@ Represents an object that can generate a description for the content of an image
 
 ## -remarks
 
+**ImageDescriptionGenerator** uses AI to produce natural-language descriptions of image content. The descriptions can be used for accessibility (alt text), search indexing, or content understanding.
+
+Before creating an **ImageDescriptionGenerator** instance, call [GetReadyState](imagedescriptiongenerator_getreadystate_1726041729.md) to check whether the model is available on the device. If the model is not ready, call [EnsureReadyAsync](imagedescriptiongenerator_ensurereadyasync_1335418254.md) to download and prepare it. Then call [CreateAsync](imagedescriptiongenerator_createasync_616540418.md) to create an instance.
+
+Call [DescribeAsync](imagedescriptiongenerator_describeasync_1940073159.md) with an image and an [ImageDescriptionKind](imagedescriptionkind.md) to specify the format of the description. The result is an [ImageDescriptionResult](imagedescriptionresult.md) containing the generated description text and a status code.
+
+The **ImageDescriptionGenerator** class implements [IDisposable](/dotnet/api/system.idisposable), so you should use a `using` statement (C#) or call **Close** (C++/WinRT) to release resources when you are done.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imagedescriptiongenerator_createasync_616540418.md

@@ -19,6 +19,10 @@ An asynchronous operation object that returns an [ImageDescriptionGenerator](ima
 
 ## -remarks
 
+Call [GetReadyState](imagedescriptiongenerator_getreadystate_1726041729.md) before calling this method. If **GetReadyState** does not return `Ready`, call [EnsureReadyAsync](imagedescriptiongenerator_ensurereadyasync_1335418254.md) first to download and install the model.
+
+The returned **ImageDescriptionGenerator** implements [IDisposable](/dotnet/api/system.idisposable). Use a `using` statement (C#) or call **Close** (C++/WinRT) to release resources when you are done.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imagedescriptiongenerator_describeasync_1940073159.md

@@ -33,6 +33,12 @@ An asynchronous operation with progress object which, when it completes, contain
 
 ## -remarks
 
+The [ImageDescriptionKind](imagedescriptionkind.md) parameter controls the format and detail level of the description. Choose `BriefDescription` for a short caption, `DetailedDescription` for more thorough coverage, `DiagramDescription` for diagrams and charts, or `AccessibleDescription` for accessibility-optimized alt text.
+
+The [ContentFilterOptions](../microsoft.windows.ai.contentmoderation/contentfilteroptions.md) parameter lets you configure the content moderation severity levels.
+
+The returned [ImageDescriptionResult](imagedescriptionresult.md) contains the generated [Description](imagedescriptionresult_description.md) text and a [Status](imagedescriptionresult_status.md) code.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imagedescriptiongenerator_ensurereadyasync_1335418254.md

@@ -19,6 +19,8 @@ An asynchronous operation with progress object that returns an [AIFeatureReadyRe
 
 ## -remarks
 
+Call [GetReadyState](imagedescriptiongenerator_getreadystate_1726041729.md) before calling this method to determine whether the model needs to be installed. If the model is already ready, you can skip calling **EnsureReadyAsync** and proceed directly to [CreateAsync](imagedescriptiongenerator_createasync_616540418.md).
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imagedescriptiongenerator_getreadystate_1726041729.md

@@ -21,6 +21,8 @@ Returns `Ready` if the underlying language model is installed.
 
 ## -remarks
 
+Use this method to check whether the image description model is available on the device before calling [CreateAsync](imagedescriptiongenerator_createasync_616540418.md). If the returned state is `EnsureNeeded`, call [EnsureReadyAsync](imagedescriptiongenerator_ensurereadyasync_1335418254.md) to download and install the model.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imagedescriptionkind.md

@@ -33,6 +33,8 @@ Generated description is optimized for accessibility.
 
 ## -remarks
 
+Specifies the format and detail level of a description generated by [ImageDescriptionGenerator.DescribeAsync](imagedescriptiongenerator_describeasync_1940073159.md). Choose the kind that best matches your use case — for example, use `AccessibleDescription` when generating alt text for screen readers, or `DiagramDescription` for flowcharts and technical diagrams.
+
 ## -see-also
 
 [DescribeAsync](imagedescriptiongenerator_describeasync_1940073159.md), [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imageobjectextractor.md

@@ -15,6 +15,14 @@ Represents an object that can extract artifacts from an image.
 
 ## -remarks
 
+**ImageObjectExtractor** uses AI to identify and segment specific objects within an image. You provide hints in the form of points and rectangles through an [ImageObjectExtractorHint](imageobjectextractorhint.md), and the extractor returns a mask of the identified object.
+
+Create an **ImageObjectExtractor** from either a [SoftwareBitmap](/uwp/api/windows.graphics.imaging.softwarebitmap) using [CreateWithSoftwareBitmapAsync](imageobjectextractor_createwithsoftwarebitmapasync_1289883320.md) or an [ImageBuffer](/windows/windows-app-sdk/api/winrt/microsoft.graphics.imaging.imagebuffer) using [CreateWithImageBufferAsync](imageobjectextractor_createwithimagebufferasync_698545862.md). Both factory methods first load and analyze the source image.
+
+After creating the extractor, call [GetSoftwareBitmapObjectMask](imageobjectextractor_getsoftwarebitmapobjectmask_775650447.md) or [GetImageBufferObjectMask](imageobjectextractor_getimagebufferobjectmask_396059515.md) with an **ImageObjectExtractorHint** to retrieve the object mask.
+
+The **ImageObjectExtractor** class implements [IDisposable](/dotnet/api/system.idisposable), so you should use a `using` statement (C#) or call **Close** (C++/WinRT) to release resources when you are done.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imageobjectextractorhint.md

@@ -15,6 +15,10 @@ Represents an object that helps an [ImageObjectExtractor](imageobjectextractor.m
 
 ## -remarks
 
+Use **ImageObjectExtractorHint** to guide an [ImageObjectExtractor](imageobjectextractor.md) toward the object you want to segment. You can specify points that should be included in the extracted region through [IncludePoints](imageobjectextractorhint_includepoints.md), points that should be excluded through [ExcludePoints](imageobjectextractorhint_excludepoints.md), and rectangular regions that contain the target object through [IncludeRects](imageobjectextractorhint_includerects.md).
+
+Combining include and exclude points gives you fine-grained control when multiple objects are close together.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imageobjectremover.md

@@ -15,6 +15,14 @@ Represents an object that can remove artifacts from images.
 
 ## -remarks
 
+**ImageObjectRemover** uses AI to erase objects from an image and fill the erased area with a reconstruction of the background. This is useful for removing unwanted elements from photos while preserving a natural appearance.
+
+Before creating an **ImageObjectRemover** instance, call [GetReadyState](imageobjectremover_getreadystate_1726041729.md) to check whether the model is available on the device. If the model is not ready, call [EnsureReadyAsync](imageobjectremover_ensurereadyasync_1335418254.md) to download and prepare it. Then call [CreateAsync](imageobjectremover_createasync_616540418.md) to create an instance.
+
+To remove an object, you typically first use [ImageObjectExtractor](imageobjectextractor.md) to generate a mask for the object you want to remove, then pass that mask along with the source image to [RemoveFromImageBuffer](imageobjectremover_removefromimagebuffer_1878721313.md) or [RemoveFromSoftwareBitmap](imageobjectremover_removefromsoftwarebitmap_1744765345.md).
+
+The **ImageObjectRemover** class implements [IDisposable](/dotnet/api/system.idisposable), so you should use a `using` statement (C#) or call **Close** (C++/WinRT) to release resources when you are done.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imageobjectremover_createasync_616540418.md

@@ -19,6 +19,10 @@ An asynchronous operation object that returns an [ImageObjectRemover](imageobjec
 
 ## -remarks
 
+Call [GetReadyState](imageobjectremover_getreadystate_1726041729.md) before calling this method. If **GetReadyState** does not return `Ready`, call [EnsureReadyAsync](imageobjectremover_ensurereadyasync_1335418254.md) first to download and install the model.
+
+The returned **ImageObjectRemover** implements [IDisposable](/dotnet/api/system.idisposable). Use a `using` statement (C#) or call **Close** (C++/WinRT) to release resources when you are done.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imageobjectremover_ensurereadyasync_1335418254.md

@@ -19,6 +19,8 @@ An asynchronous operation with progress object that returns an [AIFeatureReadyRe
 
 ## -remarks
 
+Call [GetReadyState](imageobjectremover_getreadystate_1726041729.md) before calling this method to determine whether the model needs to be installed. If the model is already ready, you can skip calling **EnsureReadyAsync** and proceed directly to [CreateAsync](imageobjectremover_createasync_616540418.md).
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imageobjectremover_getreadystate_1726041729.md

@@ -21,6 +21,8 @@ Returns `Ready` if the underlying language model is installed.
 
 ## -remarks
 
+Use this method to check whether the object removal model is available on the device before calling [CreateAsync](imageobjectremover_createasync_616540418.md). If the returned state is `EnsureNeeded`, call [EnsureReadyAsync](imageobjectremover_ensurereadyasync_1335418254.md) to download and install the model.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging)

microsoft.windows.ai.imaging/imagescaler.md

@@ -15,6 +15,14 @@ Represents an object that can resize an image and increase or decrease its resol
 
 ## -remarks
 
+**ImageScaler** uses AI-powered Image Super Resolution to scale and sharpen images while maintaining quality. The model runs on the device's NPU for hardware-accelerated performance. Call [MaxSupportedScaleFactor](imagescaler_maxsupportedscalefactor.md) to determine the maximum scale factor available on the current device.
+
+Before creating an **ImageScaler** instance, call [GetReadyState](imagescaler_getreadystate_1726041729.md) to check whether the model is available on the device. If the model is not ready, call [EnsureReadyAsync](imagescaler_ensurereadyasync_1335418254.md) to download and prepare it. Then call [CreateAsync](imagescaler_createasync_616540418.md) to create an instance.
+
+The **ImageScaler** class implements [IDisposable](/dotnet/api/system.idisposable), so you should use a `using` statement (C#) or call **Close** (C++/WinRT) to release resources when you are done.
+
+Check the [MaxSupportedScaleFactor](imagescaler_maxsupportedscalefactor.md) property to determine the maximum scaling factor supported by the device.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging), [Image scaler walkthrough](/windows/ai/apis/imaging-tutorial)

microsoft.windows.ai.imaging/imagescaler_createasync_616540418.md

@@ -19,6 +19,10 @@ An asynchronous operation object that returns an [ImageScaler](imagescaler.md) o
 
 ## -remarks
 
+Call [GetReadyState](imagescaler_getreadystate_1726041729.md) before calling this method. If **GetReadyState** does not return `Ready`, call [EnsureReadyAsync](imagescaler_ensurereadyasync_1335418254.md) first to download and install the model.
+
+The returned **ImageScaler** implements [IDisposable](/dotnet/api/system.idisposable). Use a `using` statement (C#) or call **Close** (C++/WinRT) to release resources when you are done.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging), [Image scaler walkthrough](/windows/ai/apis/imaging-tutorial)

microsoft.windows.ai.imaging/imagescaler_ensurereadyasync_1335418254.md

@@ -19,6 +19,8 @@ An asynchronous operation with progress object that returns an [AIFeatureReadyRe
 
 ## -remarks
 
+Call [GetReadyState](imagescaler_getreadystate_1726041729.md) before calling this method to determine whether the model needs to be installed. If the model is already ready, you can skip calling **EnsureReadyAsync** and proceed directly to [CreateAsync](imagescaler_createasync_616540418.md).
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging), [Image scaler walkthrough](/windows/ai/apis/imaging-tutorial)

microsoft.windows.ai.imaging/imagescaler_getreadystate_1726041729.md

@@ -21,6 +21,8 @@ Returns `Ready` if the underlying language model is installed.
 
 ## -remarks
 
+Use this method to check whether the image scaling model is available on the device before calling [CreateAsync](imagescaler_createasync_616540418.md). If the returned state is `EnsureNeeded`, call [EnsureReadyAsync](imagescaler_ensurereadyasync_1335418254.md) to download and install the model.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging), [Image scaler walkthrough](/windows/ai/apis/imaging-tutorial)

microsoft.windows.ai.imaging/imagescaler_maxsupportedscalefactor.md

@@ -19,6 +19,8 @@ The maximum scale factor supported by the [ImageScaler](imagescaler.md).
 
 ## -remarks
 
+The maximum scale factor depends on the device hardware and model capabilities. Always check this property before requesting a specific scale factor to avoid errors.
+
 ## -see-also
 
 [Get Started with AI Imaging](/windows/ai/apis/imaging), [Image scaler walkthrough](/windows/ai/apis/imaging-tutorial)

microsoft.windows.ai.imaging/recognizedline.md

@@ -15,6 +15,8 @@ Represents a single line of text in an image detected by text recognition.
 
 ## -remarks
 
+A **RecognizedLine** represents a single line of text detected within an image by the [TextRecognizer](textrecognizer.md). Access the [Text](recognizedline_text.md) property to get the full text of the line, the [Words](recognizedline_words.md) property to iterate over individual [RecognizedWord](recognizedword.md) objects, and the [Style](recognizedline_style.md) property to check whether the text appears handwritten (with a confidence level from [LineStyleConfidence](recognizedline_linestyleconfidence.md)).
+
 ## -see-also
 
 [Get Started with AI Text Recognition (OCR)](/windows/ai/apis/text-recognition), [Text recognizer walkthrough](/windows/ai/apis/text-recognition-tutorial)

microsoft.windows.ai.imaging/recognizedtext.md

@@ -15,8 +15,10 @@ Represents the result of a text recognition operation on an image.
 
 ## -remarks
 
+**RecognizedText** contains the full result of a text recognition (OCR) operation performed by [TextRecognizer](textrecognizer.md). Access the [Lines](recognizedtext_lines.md) property to iterate over each [RecognizedLine](recognizedline.md) detected in the image. Each line in turn contains individual [RecognizedWord](recognizedword.md) objects with bounding boxes and confidence scores.
+
 ## -see-also
 
-[RecognizeTextFromImage](textrecognizer_recognizetextfromimage_2145955329.md), [RecognizeTextFromImageAsync], (textrecognizer_recognizetextfromimageasync_356575282.md), [Get Started with AI Text Recognition (OCR)](/windows/ai/apis/text-recognition), [Text recognizer walkthrough](/windows/ai/apis/text-recognition-tutorial)
+[RecognizeTextFromImage](textrecognizer_recognizetextfromimage_2145955329.md), [RecognizeTextFromImageAsync](textrecognizer_recognizetextfromimageasync_356575282.md), [Get Started with AI Text Recognition (OCR)](/windows/ai/apis/text-recognition), [Text recognizer walkthrough](/windows/ai/apis/text-recognition-tutorial)
 
 ## -examples

microsoft.windows.ai.imaging/textrecognizer.md

@@ -15,7 +15,13 @@ Represents an object that can perform AI-based optical character recognition (OC
 
 ## -remarks
 
-Can be used to identify characters, words, lines, polygonal text boundaries, and provide confidence levels for each match.
+**TextRecognizer** performs AI-powered optical character recognition (OCR) on images using hardware acceleration on devices with a neural processing unit (NPU). It is faster and more accurate than the legacy [Windows.Media.Ocr.OcrEngine](/uwp/api/windows.media.ocr.ocrengine) APIs.
+
+Before creating a **TextRecognizer** instance, call [GetReadyState](textrecognizer_getreadystate_1726041729.md) to check whether the model is available on the device. If the model is not ready, call [EnsureReadyAsync](textrecognizer_ensurereadyasync_1335418254.md) to download and prepare it. Then call [CreateAsync](textrecognizer_createasync_616540418.md) to create an instance.
+
+Call [RecognizeTextFromImage](textrecognizer_recognizetextfromimage_2145955329.md) or [RecognizeTextFromImageAsync](textrecognizer_recognizetextfromimageasync_356575282.md) with an [ImageBuffer](/windows/windows-app-sdk/api/winrt/microsoft.graphics.imaging.imagebuffer) to get a [RecognizedText](recognizedtext.md) result containing detected lines, words, bounding boxes, and confidence levels.
+
+The **TextRecognizer** class implements [IDisposable](/dotnet/api/system.idisposable), so you should use a `using` statement (C#) or call **Close** (C++/WinRT) to release resources when you are done.
 
 ## -see-also
 

microsoft.windows.ai.imaging/textrecognizer_createasync_616540418.md

@@ -19,6 +19,10 @@ An asynchronous operation object that returns a [TextRecognizer](textrecognizer.
 
 ## -remarks
 
+Call [GetReadyState](textrecognizer_getreadystate_1726041729.md) before calling this method. If **GetReadyState** does not return `Ready`, call [EnsureReadyAsync](textrecognizer_ensurereadyasync_1335418254.md) first to download and install the model.
+
+The returned **TextRecognizer** implements [IDisposable](/dotnet/api/system.idisposable). Use a `using` statement (C#) or call **Close** (C++/WinRT) to release resources when you are done.
+
 ## -see-also
 
 [Get Started with AI Text Recognition (OCR)](/windows/ai/apis/text-recognition), [Text recognizer walkthrough](/windows/ai/apis/text-recognition-tutorial)

microsoft.windows.ai.imaging/textrecognizer_ensurereadyasync_1335418254.md

@@ -19,6 +19,10 @@ An asynchronous operation with progress object that returns an [AIFeatureReadyRe
 
 ## -remarks
 
+Call [GetReadyState](textrecognizer_getreadystate_1726041729.md) before calling this method to determine whether the model needs to be installed. If the model is already ready, you can skip calling **EnsureReadyAsync** and proceed directly to [CreateAsync](textrecognizer_createasync_616540418.md).
+
+The progress value (a `double`) indicates the download and installation progress. Check the [AIFeatureReadyResult.Status](../microsoft.windows.ai/aifeaturereadyresult_status.md) property to confirm success.
+
 ## -see-also
 
 [Get Started with AI Text Recognition (OCR)](/windows/ai/apis/text-recognition), [Text recognizer walkthrough](/windows/ai/apis/text-recognition-tutorial)

microsoft.windows.ai.imaging/textrecognizer_getreadystate_1726041729.md

@@ -21,6 +21,8 @@ Returns `Ready` if the underlying language model is installed.
 
 ## -remarks
 
+Use this method to check whether the text recognition model is available on the device before calling [CreateAsync](textrecognizer_createasync_616540418.md). If the returned state is `EnsureNeeded`, call [EnsureReadyAsync](textrecognizer_ensurereadyasync_1335418254.md) to download and install the model.
+
 ## -see-also
 
 [Get Started with AI Text Recognition (OCR)](/windows/ai/apis/text-recognition), [Text recognizer walkthrough](/windows/ai/apis/text-recognition-tutorial)

microsoft.windows.ai.imaging/textrecognizer_recognizetextfromimage_2145955329.md

@@ -25,6 +25,12 @@ The result of a text recognition operation on an image.
 
 ## -remarks
 
+Performs synchronous text recognition on the image. The image must be provided as an [ImageBuffer](/windows/windows-app-sdk/api/winrt/microsoft.graphics.imaging.imagebuffer), which you can create from a [SoftwareBitmap](/uwp/api/windows.graphics.imaging.softwarebitmap) using `ImageBuffer.CreateBufferAttachedToBitmap` or `ImageBuffer.CreateCopyFromBitmap`.
+
+The returned [RecognizedText](recognizedtext.md) contains a collection of [RecognizedLine](recognizedline.md) objects. Each line provides the recognized [Text](recognizedline_text.md), individual [Words](recognizedline_words.md) with bounding boxes and confidence scores, and a [Style](recognizedline_style.md) indicator.
+
+For asynchronous processing, use [RecognizeTextFromImageAsync](textrecognizer_recognizetextfromimageasync_356575282.md) instead.
+
 ## -see-also
 
 [Get Started with AI Text Recognition (OCR)](/windows/ai/apis/text-recognition), [Text recognizer walkthrough](/windows/ai/apis/text-recognition-tutorial)