Feedback on SDK design/implementation.

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/_document_analysis_client.py

@@ -79,15 +79,17 @@ def begin_analyze_document(self, model, document, **kwargs):
 
         :param str model: A unique model identifier can be passed in as a string.
             Use this to specify the custom model ID or prebuilt model ID. Prebuilt model IDs to use are:
+#### [Paul] Ideally, link to service documentation page listing all prebuilt models.
             "prebuilt-receipt", "prebuilt-invoice", "prebuilt-idDocument", "prebuilt-businessCard",
             "prebuilt-document", "prebuilt-layout".
         :param document: JPEG, PNG, PDF, TIFF, or BMP type file stream or bytes.
         :type document: bytes or IO[bytes]
+#### [Paul] Note with latest Swagger, pages should be just a string.        
         :keyword list[str] pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
             and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
             `pages=["1-3", "5-6"]`. Separate each page number or range with a comma.
-        :keyword str locale: Locale of the document. Supported locales include: en-US, en-AU, en-CA, en-GB,
-            and en-IN.
+#### [Paul] Link to service documentation for supported locales for each model.            
+        :keyword str locale: Locale hint of the input document.
         :keyword str continuation_token: A continuation token to restart a poller from a saved state.
         :return: An instance of an LROPoller. Call `result()` on the poller
             object to return a :class:`~azure.ai.formrecognizer.AnalyzeResult`.
@@ -137,13 +139,13 @@ def begin_analyze_document_from_url(self, model, document_url, **kwargs):
             Use this to specify the custom model ID or prebuilt model ID. Prebuilt model IDs to use are:
             "prebuilt-receipt", "prebuilt-invoice", "prebuilt-idDocument", "prebuilt-businessCard",
             "prebuilt-document", "prebuilt-layout".
+##### [Paul] What does "encoded URL" mean?  May want to explicitly mention that it needs to be a publicly accessible URL.
         :param str document_url: The URL of the document to analyze. The input must be a valid, encoded URL
             of one of the supported formats: JPEG, PNG, PDF, TIFF, or BMP.
         :keyword list[str] pages: Custom page numbers for multi-page documents(PDF/TIFF). Input the page numbers
             and/or ranges of pages you want to get in the result. For a range of pages, use a hyphen, like
             `pages=["1-3", "5-6"]`. Separate each page number or range with a comma.
-        :keyword str locale: Locale of the document. Supported locales include: en-US, en-AU, en-CA, en-GB,
-            and en-IN.
+        :keyword str locale: Locale hint of the input document.
         :keyword str continuation_token: A continuation token to restart a poller from a saved state.
         :return: An instance of an LROPoller. Call `result()` on the poller
             object to return a :class:`~azure.ai.formrecognizer.AnalyzeResult`.

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/_document_model_administration_client.py

@@ -90,7 +90,7 @@ def __init__(self, endpoint, credential, **kwargs):
     def begin_build_model(self, source, **kwargs):
         # type: (str, Any) -> DocumentModelAdministrationLROPoller[DocumentModel]
         """Build a custom model.
-
+##### [Paul] With BYOS tying a storage account to a FR resource, customers can specify a blob container without SAS token.
         The request must include a `source` parameter that is an
         externally accessible Azure storage blob container URI (preferably a Shared Access Signature URI). Note that
         a container URI (without SAS) is accepted only when the container is public.
@@ -208,7 +208,7 @@ def _compose_callback(
                 component_models=[
                     self._generated_models.ComponentModelInfo(model_id=model_id)
                     for model_id in model_ids
-                ] if model_ids else None
+                ] if model_ids else []
             ),
             cls=kwargs.pop("cls", _compose_callback),
             polling=LROBasePolling(
@@ -249,6 +249,7 @@ def get_copy_authorization(self, **kwargs):
             ),
             **kwargs
         )
+##### [Paul] I didn't trace.  But I am surprised that serialize() returns dict.
         target = response.serialize()  # type: ignore
         return target
 

sdk/formrecognizer/azure-ai-formrecognizer/azure/ai/formrecognizer/_models.py

@@ -2080,6 +2080,7 @@ class BoundingRegion(object):
     :ivar list[~azure.ai.formrecognizer.Point] bounding_box:
         A list of 4 points representing the quadrilateral bounding box
         that outlines the text. The points are listed in clockwise
+##### [Paul] relative to the text orientation.
         order: top-left, top-right, bottom-right, bottom-left.
         Units are in pixels for images and inches for PDF.
     :ivar int page_number:
@@ -2133,6 +2134,11 @@ def from_dict(cls, data):
         )
 
 
+##### [Paul] Suggest naming this DocumentContentElement.
+#####        Propose introducing DocumentPageElement for line, blocks; 
+#####        and DocumentStructureElement for table, keyValuePair, fields, entities, etc.
+##### [Paul] I was expecting to see Span and Confidence here.
+##### [Paul] Having Content here is good.  But since SelectionMark uses State, it may be useful to hide it from IntelliSense there.
 class DocumentElement(object):
     """A DocumentElement.