docs: clarify Parameters for the add_files API

[Xiezhibin]

Summary

Related Issue: #2132

1. This PR enhances the documentation for the add_files API by:
2. Adding a parameter table to clarify the required and optional inputs and outputs.
3. Providing a complete example that includes all parameters, such as snapshot_properties and check_duplicate_files.
4. Strengthening the warning regarding the default setting of check_duplicate_files=True and the associated risks of disabling it.

[kevinjqliu]

all the paragraphs with !!! are missing the 4 spaces, like how they are written initially

the spaces are there to render these boxes correctly

could you add them back?

[Xiezhibin]

Thank you for your reply. I will submit this!

[kevinjqliu]

Suggested change

	The `check_duplicate_files` parameter is `True` by default and will check the new files against the existing Iceberg table data files to prevent duplicates. This check can be expensive for large tables with many files. It is recommended to use the default configuration. The check can be turned off by setting `check_duplicate_files=False`, but this may result in duplicate files being added to the table, which can lead to data consistency issues and potential table corruption if the same data file is added multiple times.
	The `check_duplicate_files` parameter controls whether the method checks if any of the provided `file_paths` are already present in the Iceberg table. By default, it is set to `True`, which performs a validation against the table’s current data files to prevent accidental duplication.
	This check helps maintain data consistency by ensuring that the same data file is not added multiple times. However, for tables with a large number of files, this validation can be expensive in terms of performance.
	To skip the duplicate check, set `check_duplicate_files=False`. This can improve performance but increases the risk of introducing duplicate files, which may lead to data inconsistency or table corruption if the same file is added more than once.

I used LLM to generate this based on the function definition. WDYT?

[Xiezhibin]

Thank you for your guidance; it makes a lot of sense. I appreciate your insights, and I believe it would be beneficial to offer users a clear recommendation. for example, it would be wise to suggest keeping the check_duplicate_files parameter set to True by default to help ensure data consistency and avoid accidental duplication. If users do experience performance bottlenecks related to the validation process, they might then consider setting it to False.