Document the need to destroy a bean that was injected via Instance

As written in the post, it is necessary to manually destroy beans created with Instance#get. The current documentation only says

Provides a fully-constructed and injected instance of T.

I would say that “fully-constructed and injected” gives the impression that it is managed by the container. This will cause unobvious memory leaks. I would suggest adding something along the lines of:

The instance is created in the @Dependent(link to the docs of the annotation) scope not managed directly by the container, Therefor, its lifecycle should be handled by the caller. After using it, it should be released with a call to Instance#destroy (or CDI#destroy). Failing to do so can result in a memory leak (usually when the containing bean goes back to the pool/passivated and is not destroyed). A typical use case of such an instance is:

Instance<MyBean> creator = ...;
MyBean myBean = creator.get();
myBean.doSomething();
creator.destroy(myBean);

[Ladicek]

Since AtInject’s Provider has no way of destroying a provided instance, I don’t think we should document the need there. If anything, CDI’s Instance can override that method for the purpose of extending the javadoc.

[Ladicek]

I think the issue in AtInject is incorrect, as Instance belongs to CDI, but maybe I got confused?