[Development] gsl::owner (Was: Setters: Clarifying the ownership)

[Giuseppe D'Angelo]

Hi,

On 31/07/18 13:11, Sérgio Martins via Development wrote:
> I would recommend however that our docs show T* instead of gsl::owner<T>
> and continue to include "Takes ownership of foo" in the text.
> While I believe in self-documenting signatures I think it's too much
> noise and hurts readability, and most devs never heard of gsl.
> 
> Should be just an aid for tooling IMO.

I agree with the rest of your email, but I kind of disagree with this 
particular point, for different reasons:


* Because we need to educate our users that there's more C++ than Qt out 
there, and the Core Guidelines and the GSL are a fundamental part of 
knowledge for a C++ developer.

* Even if we consider talking about the GSL too much of a "distraction" 
in the docs, we can simply add our own qOwner type alias, with identical 
semantics, and document what it does and what it means in signatures.

* Leaving gsl::owner in the signature of a function documentation can 
help clarify situations where the textual documentation does not say 
anything about the ownership. At least, it's one more safeguard against 
adding functions that take/return pointers and don't clearly document 
the ownership.


However, from a practical point of view, unless someone adds gsl::owner 
_everywhere_ to Qt, we can't report it in the docs, as they would 
otherwise be inconsistent :-(


My 2 c,
-- 
Giuseppe D'Angelo | giuseppe.dangelo at kdab.com | Senior Software Engineer
KDAB (France) S.A.S., a KDAB Group company
Tel. France +33 (0)4 90 84 08 53, http://www.kdab.com
KDAB - The Qt, C++ and OpenGL Experts

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4007 bytes
Desc: S/MIME Cryptographic Signature
URL: <http://lists.qt-project.org/pipermail/development/attachments/20180731/171571d8/attachment.bin>