Re: [Development] From whence cometh Q_NAMESPACE?
On 11/06/2019 11.28, Matthew Woehlke wrote: > A coworker just pointed out something interesting... the documentation > of Q_NAMESPACE is in qobject.cpp, which causes it to be documented under > the documentation for QObject. However, the *definition* comes from > qobjectdefs.h, which is roughly QMetaObject, and indeed it seems like > one should not need all of QObject to use Q_NAMESPACE. Q_ENUM and > Q_ENUM_NS are in the same boat... In fact, so is Q_GADGET and everything > that can be used with Q_GADGET. > > Is this intended? Or would it make sense to move the documentation to > QMetaObject? Since code speaks louder than e-mail... https://codereview.qt-project.org/c/qt/qtbase/+/265168 -- Matthew ___ Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
Re: [Development] From whence cometh Q_NAMESPACE?
On 11/06/2019 13.58, Giuseppe D'Angelo via Development wrote: > On 11/06/2019 19:24, Matthew Woehlke wrote: >> So, my questions are: >> >> 1. Is it really Qt's intent that using Q_NAMESPACE, etc. requires >> including ? >> >> 2. If not, is it worth tweaking the documentation to make it clearer >> that is sufficient? >> >> (I don't see why we would need to "specify that macro for multiple >> targets"... just "move" it to QMetaObject. It should be clear that >> includes .) > > I wouldn't rely on that transitive inclusion. Considering that QObject uses sub-types of QMetaObject, I think it's pretty safe... > Anyhow, we have two problems at hand: > > * one is a documentation one: how do we make these macros discoverable > without spreading in N documentation pages? I'm not convinced this is a problem, given the ability to add links. (Personally, I *never* would have guessed to look for Q_NAMESPACE in qobject.html, so I guess we couldn't do worse than now.) > How do we specify what's the right include to get a macro (when it's > a transitive include like this one)? That's a much more interesting question. Right now, I'm not sure we "specify" this at all. Kyle is implicitly going by which class's documentation includes the macro (which isn't unreasonable), but that's not very explicit. > * another one is which one is the "right" include for pulling in the > meta object macros. It could even be an include different from QObject > and QMetaObject... In general, I agree. (In practice, I would argue that right now *is* the correct answer for those moc-related macros that don't explicitly depend on QObject. For Q_OBJECT itself, of course, and the signal/slot macros, I would argue for , because good luck having a Q_OBJECT that doesn't ultimately derive from QObject.) -- Matthew ___ Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
Re: [Development] From whence cometh Q_NAMESPACE?
On 11/06/2019 19:24, Matthew Woehlke wrote: So, my questions are: 1. Is it really Qt's intent that using Q_NAMESPACE, etc. requires including ? 2. If not, is it worth tweaking the documentation to make it clearer that is sufficient? (I don't see why we would need to "specify that macro for multiple targets"... just "move" it to QMetaObject. It should be clear that includes .) I wouldn't rely on that transitive inclusion. Anyhow, we have two problems at hand: * one is a documentation one: how do we make these macros discoverable without spreading in N documentation pages? How do we specify what's the right include to get a macro (when it's a transitive include like this one)? * another one is which one is the "right" include for pulling in the meta object macros. It could even be an include different from QObject and QMetaObject... Cheers, -- 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 https://lists.qt-project.org/listinfo/development
Re: [Development] From whence cometh Q_NAMESPACE?
Matthew Woehlke (11 June 2019 17:28) > A coworker just pointed out something interesting... the documentation > of Q_NAMESPACE is in qobject.cpp, which is also the .cpp file which pulls in moc_qnamespace.cpp (at its end). No, I don't know why, I just tripped over it recently ! > which causes it to be documented under > the documentation for QObject. However, the *definition* comes from > qobjectdefs.h, which is roughly QMetaObject, and indeed it seems like > one should not need all of QObject to use Q_NAMESPACE. Q_ENUM and > Q_ENUM_NS are in the same boat... In fact, so is Q_GADGET and everything > that can be used with Q_GADGET. > > Is this intended? Or would it make sense to move the documentation to > QMetaObject? It does sound bizarre, but I've no idea why it's like that. Perhaps someone with access to the pre-history in our version control can work it out. Eddy. ___ Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
Re: [Development] From whence cometh Q_NAMESPACE?
On 11/06/2019 12.30, Giuseppe D'Angelo via Development wrote: > Il 11/06/19 17:28, Matthew Woehlke ha scritto: >> [...] would it make sense to move the documentation [of >> Q_NAMESPACE, Q_ENUM, etc.] to QMetaObject? > > Well, also Q_OBJECT itself, Q_SIGNALS/Q_SLOTS, etc. appear in > qobjectdefs.h, yet obviously the right place for documented them is > QObject. Agreed in both respects. (Yes, it's correct. Yes, it is obviously so.) > So I think the other macros just followed suit. Maybe it's > possible to specify that macro for multiple targets, but is it worth it? (For context: https://github.com/Kitware/seal-tk/pull/28.) As it stands, the doc "implies" that `#include ` is required to use Q_NAMESPACE and friends. But this is overkill, and in (current) reality, is sufficient. So, my questions are: 1. Is it really Qt's intent that using Q_NAMESPACE, etc. requires including ? 2. If not, is it worth tweaking the documentation to make it clearer that is sufficient? (I don't see why we would need to "specify that macro for multiple targets"... just "move" it to QMetaObject. It should be clear that includes .) -- Matthew ___ Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
Re: [Development] From whence cometh Q_NAMESPACE?
On Tue, 2019-06-11 at 18:30 +0200, Giuseppe D'Angelo via Development wrote: > > Is this intended? Or would it make sense to move the documentation > > to > > QMetaObject? > Well, also Q_OBJECT itself, Q_SIGNALS/Q_SLOTS, etc. appear in > qobjectdefs.h, yet obviously the right place for documented them is > QObject. So I think the other macros just followed suit. Maybe it's > possible to specify that macro for multiple targets, but is it worth > it? For my use case, I'm wondering if using Q_NAMESPACE with #include is officially supported, or if it's an implementation detail that just "happens to work" and could break. What is the officially supported header for Q_NAMESPACE? Kyle ___ Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
Re: [Development] From whence cometh Q_NAMESPACE?
Hi, Il 11/06/19 17:28, Matthew Woehlke ha scritto: A coworker just pointed out something interesting... the documentation of Q_NAMESPACE is in qobject.cpp, which causes it to be documented under the documentation for QObject. Technically, it's the \relates command that puts it in the QObject's docs, not the fact that it appears in qobject.cpp. However, the*definition* comes from qobjectdefs.h, which is roughly QMetaObject, and indeed it seems like one should not need all of QObject to use Q_NAMESPACE. Q_ENUM and Q_ENUM_NS are in the same boat... In fact, so is Q_GADGET and everything that can be used with Q_GADGET. Is this intended? Or would it make sense to move the documentation to QMetaObject? Well, also Q_OBJECT itself, Q_SIGNALS/Q_SLOTS, etc. appear in qobjectdefs.h, yet obviously the right place for documented them is QObject. So I think the other macros just followed suit. Maybe it's possible to specify that macro for multiple targets, but is it worth it? Cheers, -- 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: Firma crittografica S/MIME ___ Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
[Development] From whence cometh Q_NAMESPACE?
A coworker just pointed out something interesting... the documentation of Q_NAMESPACE is in qobject.cpp, which causes it to be documented under the documentation for QObject. However, the *definition* comes from qobjectdefs.h, which is roughly QMetaObject, and indeed it seems like one should not need all of QObject to use Q_NAMESPACE. Q_ENUM and Q_ENUM_NS are in the same boat... In fact, so is Q_GADGET and everything that can be used with Q_GADGET. Is this intended? Or would it make sense to move the documentation to QMetaObject? -- Matthew ___ Development mailing list Development@qt-project.org https://lists.qt-project.org/listinfo/development
