document which function calls increment / decrement refcounts for handles

[JohnPJenkins]

In an earlier meeting, there was some confusion about handle management. I.e. when must HG_Destroy be called? Clearing up this confusion amounts to improving documentation on when handle refcounts are modified. For instance, HG_Forward and HG_Bulktransfer each increment handle recounts, and the corresponding callbacks are expected to HG(Bulk_)Destroy (decrement the refcount) when they are finished with it.

[soumagne]

Yes that's true the question comes back all the time so that's something we need to clarify. Thanks!

[carns]

One thing that I think would be good to put down as a "line in the sand" when documenting this, is that the API user should treat HG_Destroy() as a promise that the API user will not touch the handle again.

In other words, the reference counting that's going on is for Mercury's benefit (so that if it needs to live longer to wrap up some in-flight operation it can do so), not something that the caller should rely on as a way to continue poking at the handle after Destroy().