Provide easy way to retain-construct from a reference

[Manishearth]

Currently ComPtr::from_raw adopts the given pointer, which means that it assumes that it has already been addreffed.

This isn't always true, though, sometimes you want to retain the refcount of the old pointer, which you're simply borrowing from to create a new reference. We should have a separate constructor for this, the current way of doing it is to mem::forget(ptr.clone()) which is clunky.

[retep998]

Something like ComPtr::clone_from_raw?

[Manishearth]

Yep!

[mildcwen]

@retep998 @Manishearth How about manully call Release instead of impl Drop?
The main reason for i use ComPtr just want to wrap the raw pointer to call it's method.. use Deref to instead (ptr -> m() in C ),

if need change RefCount, we could call clone() or Release() explicitly

    pub unsafe fn from_fn<F>(fun: F) -> Result<ComPtr<T>, HRESULT>
    where
        T: Interface,
        F: FnOnce(*mut *mut T) -> HRESULT,
{}

// I had change the signature like this, but still not ideal.
// I think just need new()/from_raw(), to Construct,

This is common to store pointer in WndExtraMemtory, and to retrieve, as raw pointer, ComPtr::new(p), deal something, then leave without Release...

[Manishearth]

I mean yes, there are many ways to make it work, but in this case adopt/retain semantics are a common difference and I think it would be good for documentation, even, to have both as first class APIs that are well documented.