FileComment model includes is_whole/quote fields but they are silently ignored when creating comments on docx files

[tonyzdev]

Summary

The FileComment model and its FileCommentBuilder expose is_whole and quote fields, suggesting that inline (non-whole-document) comments can be created via the API. However, when calling POST /open-apis/drive/v1/files/{file_token}/comments with file_type=docx, these fields are silently ignored — the API always creates a global (whole-document) comment regardless of the values passed.

Steps to Reproduce

import httpx

body = {
    "is_whole": False,
    "quote": "目标是验证文档导入与结构化展示",  # exact text from the document
    "reply_list": {
        "replies": [{
            "content": {
                "elements": [
                    {"type": "text_run", "text_run": {"text": "This should be an inline comment"}}
                ]
            }
        }]
    }
}

resp = httpx.post(
    "https://open.larksuite.com/open-apis/drive/v1/files/{file_token}/comments",
    headers={"Authorization": f"Bearer {tenant_access_token}"},
    params={"file_type": "docx"},
    json=body,
    timeout=15,
)

Expected Behavior

The comment should be created as an inline comment anchored to the quoted text, with is_whole=False in the response.

Actual Behavior

The API returns code: 0 (success), but when retrieving the comment via the List API:

{
  "comment_id": "...",
  "is_whole": true,
  "quote": "",
  ...
}

The comment is always a global comment (is_whole=true, quote=""), no matter what is_whole or quote values are sent in the request.

Test Details

Tested with 5 different quote values against a real docx document:

quote value	Result
Exact substring with punctuation	is_whole=true, quote=""
Full sentence from document	is_whole=true, quote=""
Partial text match	is_whole=true, quote=""
Heading text	is_whole=true, quote=""
Empty (no quote)	is_whole=true, quote=""

All 5 comments were created as global comments.

The Problem

The SDK's auto-generated FileComment model uses the same class for both request and response, so it exposes builder methods for is_whole() and quote():

# file_comment.py (auto-generated)
class FileCommentBuilder(object):
    def is_whole(self, is_whole: bool) -> "FileCommentBuilder":
        self._file_comment.is_whole = is_whole
        return self

    def quote(self, quote: str) -> "FileCommentBuilder":
        self._file_comment.quote = quote
        return self

This is misleading because:

1. Developers assume these fields are functional for creation since the builder exposes them
2. The API accepts the request without any error or warning — it just silently ignores the fields
3. The official documentation page is titled "Add a Global Comment" but this isn't obvious when using the SDK

Suggestion

One or more of the following would help:

1. Document the limitation — Clarify in the API docs that is_whole and quote are response-only fields, not accepted in the create request body for docx files
2. Separate request/response models — Use a dedicated CreateFileCommentRequestBody that only includes reply_list, instead of reusing FileComment
3. Support inline comments — If this is a missing feature, it would be very useful to support creating inline comments via the API (the UI already supports this)
4. Return an error — If is_whole=False or quote is passed but not supported, return an error code instead of silently ignoring

Environment

• SDK version: latest (lark-oapi from PyPI)
• API base: https://open.larksuite.com/open-apis
• Document type: docx (New Doc)
• Auth: tenant_access_token