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.dang...@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
smime.p7s
Description: S/MIME Cryptographic Signature
_______________________________________________ Development mailing list Development@qt-project.org http://lists.qt-project.org/mailman/listinfo/development
