Internal: 4 call sites in Paragraph.swift still use deprecated paragraph.commentIds (post-#6 cleanup)

[kiki830621]

Current Status

Phase: implemented
Last updated: 2026-05-02
Implementation: PR #35 / commit e63baaa
Verification: swift build; focused swift test --filter InsertLocationTests|ParagraphTests|Issue56RoundtripCompletenessTests|Issue6RoundtripLoudFailTests; full swift test (830 tests, 1 skipped, 0 failures)

Notes: Public Paragraph.commentIds remains as the deprecated compatibility API, while internal emit and comment mutation paths now use non-deprecated backing storage/mutators. swift build no longer reports source warnings for commentIds.

Problem

After #6 (v0.21.4) deprecated Run.commentIds and Paragraph.commentIds, 4 internal sites in Sources/OOXMLSwift/Models/Paragraph.swift still read from the deprecated property, producing build warnings:

Paragraph.swift:
  ⚠ [Line 409:26] 'commentIds' is deprecated
  ⚠ [Line 446:26] 'commentIds' is deprecated
  ⚠ [Line 546:26] 'commentIds' is deprecated
  ⚠ [Line 730:26] 'commentIds' is deprecated

These are internal consumers of the property, not external API users — the deprecation warning IS firing on our own code.

Type

tech-debt / cleanup

Severity

LOW (good first issue) — pure migration, ~4 sites, follows the same pattern documented in the deprecation message:

Use commentRangeMarkers (source of truth since Phase 4) or the computed commentRangeIds. Stored commentIds is no longer populated by Reader since v0.21.4 and will be removed in v0.22.

Expected

Replace each paragraph.commentIds read with either:

• paragraph.commentRangeIds (computed from commentRangeMarkers) — preferred drop-in replacement
• paragraph.commentRangeMarkers.compactMap { ... } — if richer marker info is needed

After migration, build should be deprecation-free for commentIds. Public surface unchanged (deprecated setters still work for downstream callers until v0.22 removal).

Why surface this now

These warnings became visible after #6 shipped (v0.21.4); the LSP diagnostic refresh during #15 docs work made them obvious. Fixing them is a prerequisite for the v0.22 milestone (where commentIds storage gets removed entirely — internal sites would fail to compile).

Related

• Wrapper roundtrip completeness: AlternateContent fallbackRuns drift + comment marker emit asymmetry (post-#56 follow-up) #6 — Wrapper roundtrip completeness (introduced the deprecation)
• v0.22 milestone — commentIds removal alongside Hyperlink.text setter (API mutation surface lossy: Hyperlink.text setter + default position=0 collision + xml:space loss (post-#56 follow-up) #5) and insertEquation(at: String, ...) (DocxReader never populates WordDocument.sectionProperties from the body-level <w:sectPr> #84 in che-word-mcp)

[kiki830621]

Implementation Plan

Scope

Remove internal deprecation warnings from Paragraph.swift while keeping the deprecated public commentIds compatibility surface alive until v0.22.

Plan

• Convert commentIds from deprecated stored property to deprecated computed property backed by a private storage field.
• Update internal emit paths to read the private backing storage instead of the deprecated public property.
• Preserve legacy API-built comment output semantics and existing tests.
• Verify with swift build and focused paragraph/comment tests.

[kiki830621]

📝 Note

Source: implementation commit e63baaa / PR #35
Date: 2026-05-02

論述

#18 的實作已完成。公開的 Paragraph.commentIds 仍保留為 deprecated 相容 API，但現在改為 private legacyCommentIds 的 computed wrapper；Paragraph 內部 emit 路徑與 WordDocument.insertComment/deleteComment 改走非 deprecated 的 backing/mutator 路徑。因此 swift build 不再對 source code 產生 commentIds deprecation warning，外部呼叫者的既有 setter/getter 相容性則維持到 v0.22 移除前。

Details

• Commit: e63baaa
• PR: Clean up comment IDs and insert location errors #35
• Verification: swift build; focused swift test --filter InsertLocationTests|ParagraphTests|Issue56RoundtripCompletenessTests|Issue6RoundtripLoudFailTests; full swift test (830 tests, 1 skipped, 0 failures)