[SAMPLE-DOC] update sample description

Author: Chien Yuan Chang

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_analyze_binary_async.py

@@ -8,8 +8,10 @@
 FILE: sample_analyze_binary_async.py
 
 DESCRIPTION:
-    This sample demonstrates how to analyze a PDF file from disk using the `prebuilt-documentSearch`
-    analyzer (async version).
+    This sample demonstrates how to analyze a PDF file from disk using the prebuilt-documentSearch
+    analyzer.
+
+    ## About analyzing documents from binary data
 
     One of the key values of Content Understanding is taking a content file and extracting the content
     for you in one call. The service returns an AnalyzeResult that contains an array of MediaContent
@@ -20,13 +22,24 @@
     This sample focuses on document analysis. For prebuilt RAG analyzers covering images, audio, and
     video, see sample_analyze_url_async.py.
 
-    The prebuilt-documentSearch analyzer transforms unstructured documents into structured, machine-
-    readable data optimized for RAG scenarios. It generates rich GitHub Flavored Markdown that preserves
-    document structure and can include structured text, tables (in HTML format), charts and diagrams,
-    mathematical formulas, hyperlinks, barcodes, annotations, and page metadata.
+    ## Prebuilt analyzers
+
+    Content Understanding provides prebuilt RAG analyzers (the prebuilt-*Search analyzers, such as
+    prebuilt-documentSearch) that return markdown and a one-paragraph Summary for each content item,
+    making them useful for retrieval-augmented generation (RAG) and other downstream applications:
+
+    - prebuilt-documentSearch - Extracts content from documents (PDF, images, Office documents) with
+      layout preservation, table detection, figure analysis, and structured markdown output.
+      Optimized for RAG scenarios.
+    - prebuilt-audioSearch - Transcribes audio content with speaker diarization, timing information,
+      and conversation summaries. Supports multilingual transcription.
+    - prebuilt-videoSearch - Analyzes video content with visual frame extraction, audio transcription,
+      and structured summaries. Provides temporal alignment of visual and audio content.
+    - prebuilt-imageSearch - Analyzes standalone images and returns a one-paragraph Summary of the
+      image content. For images that contain text (including hand-written text), use
+      prebuilt-documentSearch.
 
-    For documents that contain images with hand-written text, the prebuilt-documentSearch analyzer
-    includes OCR capabilities by default.
+    This sample uses prebuilt-documentSearch to extract structured content from PDF documents.
 
 USAGE:
     python sample_analyze_binary_async.py

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_analyze_configs_async.py

@@ -9,11 +9,11 @@
 
 DESCRIPTION:
     This sample demonstrates how to extract additional features from documents such as charts,
-    hyperlinks, formulas, and annotations using the `prebuilt-documentSearch` analyzer, which has
+    hyperlinks, formulas, and annotations using the prebuilt-documentSearch analyzer, which has
     formulas, layout, and OCR enabled by default.
 
 ABOUT ANALYSIS CONFIGS:
-    The `prebuilt-documentSearch` analyzer has the following configurations enabled by default:
+    The prebuilt-documentSearch analyzer has the following configurations enabled by default:
     - ReturnDetails: true - Returns detailed information about document elements
     - EnableOcr: true - Performs OCR on documents
     - EnableLayout: true - Extracts layout information (tables, figures, hyperlinks, annotations)
@@ -34,7 +34,7 @@
     the analyzer.
 
 PREREQUISITES:
-    To get started you'll need a **Microsoft Foundry resource**. See sample_update_defaults.py
+    To get started you'll need a Microsoft Foundry resource. See sample_update_defaults.py
     for setup guidance.
 
 USAGE:

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_analyze_invoice_async.py

@@ -8,18 +8,40 @@
 FILE: sample_analyze_invoice_async.py
 
 DESCRIPTION:
-    Analyze an invoice using prebuilt analyzer (async version)
+    This sample demonstrates how to analyze an invoice from a URL using the prebuilt-invoice analyzer
+    and extract structured fields from the result.
+
+    ## About analyzing invoices
+
+    Content Understanding provides a rich set of prebuilt analyzers that are ready to use without any
+    configuration. These analyzers are powered by knowledge bases of thousands of real-world document
+    examples, enabling them to understand document structure and adapt to variations in format and
+    content.
+
+    Prebuilt analyzers are ideal for:
+    - Content ingestion in search and retrieval-augmented generation (RAG) workflows
+    - Intelligent document processing (IDP) to extract structured data from common document types
+    - Agentic flows as tools for extracting structured representations from input files
+
+    ### The prebuilt-invoice analyzer
+
+    The prebuilt-invoice analyzer is a domain-specific analyzer optimized for processing invoices,
+    utility bills, sales orders, and purchase orders. It automatically extracts structured fields
+    including:
 
-    This sample demonstrates how to analyze an invoice from a URL using the `prebuilt-invoice` analyzer
-    and extract structured fields from the result. The prebuilt-invoice analyzer automatically extracts
-    structured fields including:
     - Customer/Vendor information: Name, address, contact details
     - Invoice metadata: Invoice number, date, due date, purchase order number
     - Line items: Description, quantity, unit price, total for each item
     - Financial totals: Subtotal, tax amount, shipping charges, total amount
     - Payment information: Payment terms, payment method, remittance address
 
     The analyzer works out of the box with various invoice formats and requires no configuration.
+    It's part of the financial documents category of prebuilt analyzers, which also includes:
+    - prebuilt-receipt - Sales receipts from retail and dining establishments
+    - prebuilt-creditCard - Credit card statements
+    - prebuilt-bankStatement.us - US bank statements
+    - prebuilt-check.us - US bank checks
+    - prebuilt-creditMemo - Credit memos and refund documents
 
 USAGE:
     python sample_analyze_invoice_async.py

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_analyze_url_async.py

@@ -9,18 +9,26 @@
 
 DESCRIPTION:
     Another great value of Content Understanding is its rich set of prebuilt analyzers. Great examples
-    of these are the RAG analyzers that work for all modalities (prebuilt-documentSearch, prebuilt-imageSearch,
-    prebuilt-audioSearch, and prebuilt-videoSearch).
+    of these are the RAG analyzers that work for all modalities (prebuilt-documentSearch,
+    prebuilt-imageSearch, prebuilt-audioSearch, and prebuilt-videoSearch). This sample demonstrates
+    these RAG analyzers. Many more prebuilt analyzers are available (for example, prebuilt-invoice);
+    see the invoice sample or the prebuilt analyzer documentation to explore the full list.
 
-    This sample demonstrates these RAG analyzers with URL inputs. Content Understanding supports both
-    local binary inputs (see sample_analyze_binary_async.py) and URL inputs across all modalities.
+    ## About analyzing URLs across modalities
+
+    Content Understanding supports both local binary inputs (see sample_analyze_binary_async.py) and URL
+    inputs across all modalities. This sample focuses on prebuilt RAG analyzers (the prebuilt-*Search
+    analyzers, such as prebuilt-documentSearch) with URL inputs.
 
     Important: For URL inputs, use begin_analyze() with AnalyzeInput objects that wrap the URL.
-    For binary data (local files), use begin_analyze_binary() instead.
+    For binary data (local files), use begin_analyze_binary() instead. This sample demonstrates
+    begin_analyze() with URL inputs.
 
     Documents, HTML, and images with text are returned as DocumentContent (derived from MediaContent),
     while audio and video are returned as AudioVisualContent (also derived from MediaContent). These
-    prebuilt RAG analyzers return markdown and a one-paragraph Summary for each content item.
+    prebuilt RAG analyzers return markdown and a one-paragraph Summary for each content item;
+    prebuilt-videoSearch can return multiple segments, so iterate over all contents rather than just
+    the first.
 
 USAGE:
     python sample_analyze_url_async.py

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_copy_analyzer_async.py

@@ -9,13 +9,13 @@
 
 DESCRIPTION:
     This sample demonstrates how to copy an analyzer from source to target within the same
-    resource using the copy_analyzer API. This is useful for creating copies of analyzers
-    for testing, staging, or production deployment.
+    Microsoft Foundry resource using the begin_copy_analyzer API. This is useful for
+    creating copies of analyzers for testing, staging, or production deployment.
 
-    The copy_analyzer API allows you to copy an analyzer within the same Azure resource:
+    About copying analyzers
+    The begin_copy_analyzer API allows you to copy an analyzer within the same Azure resource:
     - Same-resource copy: Copies an analyzer from one ID to another within the same resource
     - Exact copy: The target analyzer is an exact copy of the source analyzer
-    - Use cases: Testing, staging, production deployment, versioning
 
     Note: For cross-resource copying (copying between different Azure resources or subscriptions),
     use the grant_copy_auth sample instead.

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_create_analyzer_async.py

@@ -9,17 +9,38 @@
 
 DESCRIPTION:
     This sample demonstrates how to create a custom analyzer with a field schema to extract
-    structured data from documents.
+    structured data from documents. While this sample shows document modalities, custom analyzers
+    can also be created for video, audio, and image content. The same concepts apply across all
+    modalities.
 
-    Custom analyzers allow you to:
+    ## About custom analyzers
+
+    Custom analyzers allow you to define a field schema that specifies what structured data to
+    extract from documents. You can:
     - Define custom fields (string, number, date, object, array)
-    - Specify extraction methods:
-      - extract: Values are extracted as they appear in the content (literal text extraction)
-      - generate: Values are generated freely based on the content using AI models
-      - classify: Values are classified against a predefined set of categories
-    - Use prebuilt analyzers as a base (prebuilt-document, prebuilt-audio, prebuilt-video, prebuilt-image)
+    - Specify extraction methods to control how field values are extracted:
+      - generate - Values are generated freely based on the content using AI models (best for
+        complex or variable fields requiring interpretation)
+      - classify - Values are classified against a predefined set of categories (best when using
+        enum with a fixed set of possible values)
+      - extract - Values are extracted as they appear in the content (best for literal text
+        extraction from specific locations). Note: This method is only available for document
+        content. Requires estimateSourceAndConfidence to be set to true for the field.
+
+      When not specified, the system automatically determines the best method based on the field
+      type and description.
+    - Use prebuilt analyzers as a base. Supported base analyzers include:
+      - prebuilt-document - for document-based custom analyzers
+      - prebuilt-audio - for audio-based custom analyzers
+      - prebuilt-video - for video-based custom analyzers
+      - prebuilt-image - for image-based custom analyzers
     - Configure analysis options (OCR, layout, formulas)
-    - Enable source and confidence tracking for extracted field values
+    - Enable source and confidence tracking: Set estimateFieldSourceAndConfidence to true at the
+      analyzer level (in ContentAnalyzerConfig) or estimateSourceAndConfidence to true at the field
+      level to get source location (page number, bounding box) and confidence scores for extracted
+      field values. This is required for fields with method = extract and is useful for validation,
+      quality assurance, debugging, and highlighting source text in user interfaces. Field-level
+      settings override analyzer-level settings.
 
 USAGE:
     python sample_create_analyzer_async.py

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_create_classifier_async.py

@@ -8,14 +8,31 @@
 FILE: sample_create_classifier_async.py
 
 DESCRIPTION:
-    This sample demonstrates how to create a classifier analyzer to categorize documents and
-    use it to analyze documents with and without automatic segmentation.
-
-    Classifiers are a type of custom analyzer that categorize documents into predefined categories.
-    They're useful for:
-    - Document routing: Automatically route documents to the right processing pipeline
-    - Content organization: Organize large document collections by type
-    - Multi-document processing: Process files containing multiple document types by segmenting them
+    This sample demonstrates how to create a classifier analyzer to categorize documents and use it
+    to analyze documents with and without automatic segmentation.
+
+    ## About classifiers
+
+    Classifiers are a type of custom analyzer that create classification workflows to categorize
+    documents into predefined custom categories using ContentCategories. They allow you to perform
+    classification and content extraction as part of a single API call. Classifiers are useful for:
+    - Content organization: Organize large document collections by type through categorization
+    - Data routing (optional): Optionally route your data to specific custom analyzers based on
+      category, ensuring your data is routed to the best analyzer for processing when needed
+    - Multi-document processing: Process files containing multiple document types by automatically
+      segmenting them
+
+    Classifiers use custom categories to define the types of documents they can identify. Each
+    category has a Description that helps the AI model understand what documents belong to that
+    category. You can define up to 200 category names and descriptions. You can include an "other"
+    category to handle unmatched content; otherwise, all files are forced to be classified into one
+    of your defined categories.
+
+    The enable_segment property in the analyzer configuration controls whether multi-document files
+    are split into segments:
+    - enable_segment = False: Classifies the entire file as a single category (classify only)
+    - enable_segment = True: Automatically splits the file into segments by category (classify and
+      segment)
 
 USAGE:
     python sample_create_classifier_async.py

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_delete_result_async.py

@@ -12,10 +12,14 @@
     This is useful for removing temporary or sensitive analysis results immediately, rather
     than waiting for automatic deletion after 24 hours.
 
-    Analysis results are stored temporarily and can be deleted using the delete_result API:
-    - Immediate deletion: Results are marked for deletion and permanently removed
-    - Automatic deletion: Results are automatically deleted after 24 hours if not manually deleted
-    - Operation ID required: You need the operation ID from the analysis operation to delete
+    About deleting results:
+    Analysis results from analyze or begin_analyze are automatically deleted after 24 hours.
+    However, you may want to delete results earlier in certain cases:
+    - Remove sensitive data immediately: Ensure sensitive information is not retained longer than necessary
+    - Comply with data retention policies: Meet requirements for data deletion
+
+    To delete results earlier than the 24-hour automatic deletion, use delete_result.
+    This method requires the operation ID from the analysis operation.
 
     Important: Once deleted, results cannot be recovered. Make sure you have saved any data
     you need before deleting.

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_get_analyzer_async.py

@@ -11,14 +11,18 @@
     This sample demonstrates how to retrieve information about analyzers, including prebuilt
     analyzers and custom analyzers.
 
-    The get_analyzer method allows you to retrieve detailed information about any analyzer:
-    - Prebuilt analyzers: System-provided analyzers like prebuilt-documentSearch, prebuilt-invoice
+    ## About getting analyzer information
+
+    The get_analyzer method allows you to retrieve detailed information about any analyzer,
+    including:
+    - Prebuilt analyzers: System-provided analyzers like prebuilt-documentSearch, prebuilt-invoice,
+      etc.
     - Custom analyzers: Analyzers you've created with custom field schemas or classifiers
 
     This is useful for:
-    - Verifying analyzer configuration
-    - Inspecting prebuilt analyzers to learn about their capabilities
-    - Debugging analyzer behavior
+    - Verifying analyzer configuration: Check the current state of an analyzer
+    - Inspecting prebuilt analyzers: Learn about available prebuilt analyzers and their capabilities
+    - Debugging: Understand why an analyzer behaves a certain way
 
 USAGE:
     python sample_get_analyzer_async.py

sdk/contentunderstanding/azure-ai-contentunderstanding/samples/async_samples/sample_get_result_file_async.py

@@ -9,18 +9,18 @@
 
 DESCRIPTION:
     This sample demonstrates how to retrieve result files (such as keyframe images) from a
-    video analysis operation using the `get_result_file` API.
+    video analysis operation using the get_result_file API.
 
     About result files:
     When analyzing video content, the Content Understanding service can generate result files such as:
     - Keyframe images: Extracted frames from the video at specific timestamps
     - Other result files: Additional files generated during analysis
 
-    The `get_result_file` API allows you to retrieve these files using:
+    The get_result_file API allows you to retrieve these files using:
     - Operation ID: Extracted from the analysis operation
     - File path: The path to the specific result file. In the recording, keyframes were accessed
-                 with paths like `keyframes/733` and `keyframes/9000`, following the
-                 `keyframes/{frameTimeMs}` pattern.
+                 with paths like keyframes/733 and keyframes/9000, following the
+                 keyframes/{frameTimeMs} pattern.
 
 USAGE:
     python sample_get_result_file_async.py