Document copy vs borrow semantics of FFI functions

[cstepanian]

Some iterators return copies to Rust data that need to be deleted with specific functions.
Others merely return pointers (borrows) to data, that the caller need not manually clean up,
other than making sure that the pointer does not dangle after the underlying storage is freed.

Note that all Iterators need to be deleted after use -- it is only the items that may or may not
be copied.

Iterators which only borrow for each item:

• ProviderStateIterator
• MessagePactMessageIterator

Iterators which allocate for each item:

• MessageMetadataIterator (message_metadata_pair_delete)
• ProviderStateParamIterator (provider_state_param_pair_delete)
• MessagePactMetadataIterator (message_pact_metadata_triple_delete)