add hive catalog table properties docs and refactor

[kevinjqliu]

Rationale for this change

Follow up to #2927
Add notes on updating iceberg table properties and hive table properties when using the hive catalog (HMS)
Minor refactor on variable naming to be more explicit

Are these changes tested?

Are there any user-facing changes?

[Copilot]

Pull request overview

This pull request adds comprehensive documentation explaining the interaction between Iceberg table properties and HMS (Hive Metastore) table properties, along with a minor refactoring to improve variable naming clarity.

Changes:

• Added detailed documentation comments explaining how Iceberg and HMS properties are synchronized during table commits
• Refactored variable names to be more explicit (new_parameters → new_iceberg_properties, removed_keys → deleted_iceberg_properties, merged_params → existing_hms_parameters)
• Updated inline comments to better describe the merge operation

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The comment uses "it's" (contraction) but the rest of the documentation uses full words. For consistency and formality in code documentation, consider using "it is" instead of "it's".

Suggested change

	# - New/Updated HMS table properties will also be stored in Iceberg metadata (even though it's HMS-specific)
	# - New/Updated HMS table properties will also be stored in Iceberg metadata (even though it is HMS-specific)

[bharos]

Can we be more explicit here like
HMS-native properties (set outside Iceberg) cannot be deleted since they are not visible to Iceberg

because in cases like below, it can actually delete HMS properties?

# Set via Iceberg
table.updateProperties().set("hive.table_prop", "true").commit()
# → Goes to BOTH Iceberg metadata AND HMS
# → Now it's "visible" to Iceberg (tracked in Iceberg metadata)

# Unset via Iceberg
table.updateProperties().remove("hive.table_prop").commit()
# → deleted_iceberg_properties = {"hive.table_prop"}
# → Removed from BOTH Iceberg metadata AND HMS ✅

[kevinjqliu]

yea good point!

[Fokko]

Thanks for clarifying this @kevinjqliu 👍