Re: [Development] API style guide: scoped enum or not?

[Giuseppe D'Angelo via Development]

Il 14/06/23 14:59, Marc Mutz via Development ha scritto:

A) new enums MUST have an explicit underlying type¹²

For unscoped enums, the compiler otherwise picks one, possibly resulting
in BiC when new addtions change the underlying type or otherwise just
warnings because one compiler uses a signed and the other an unsigned
type (most recent exmaple: QTBUG-113792). For scoped enums, the type is
int, but probably not always, and why require the reader of the code to
know the C++ rules when we can make it explicit?


By the way, the last sentence is not entirely correct. For scoped enums 
that don't specify otherwise, the underlying type is int, always. File 
under another advantage of using "enum class". Explicitly stating the 
underlying type for enum classes makes me actually wonder that there 
might be something tricky going on (e.g. the enum is being shoved into a 
bitfield or so). I'd rather just see "by default" `enum class Foo {`.


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: Firma crittografica S/MIME
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Marc Mutz via Development]

On 14.06.23 14:59, Marc Mutz via Development wrote:
> A) new enums MUST have an explicit underlying type¹²

It's actually worse. In the 6.6 header review, several enums add 
enumerators that cross a power-of-two boundary, one even crosses 2⁸.

The C++ standard give compilers a lot of leeway in picking the 
underlying type of an unscoped enum with no explicit underlying type: 
https://eel.is/c++draft/dcl.enum#7

I would propose, therefore, two following, additional rule:

A2) any existing enum that gets extended MUST have a fixed³ underlying type

If it doesn't, then the commit that extends the enum MUST be prefixed by 
two other commits:
1. a commit adding a
static_assert(std::is_same_v<
std::underlying_type_t,
ExpectedType>
);
in the header file defining `Enum`. This patch MUST be picked into
the last LTS
2. if (1) has been successfully integrated into dev and the last LTS, a
commit that reverts the static_assert and fixes the enum's underlying
type. This patch MUST NOT be picked to an older branch.

After these have landed, the enum can be safely extended.

Rationale: the first patch being in the LTS branch alerts us if any 
tool-chain disagrees with our expected underlying type. If at any later 
time, we get a bug-report saying that the static_assert triggered, we 
know we have to adjust the underlying type. The second patch fixes the 
assumption, forcing the compiler to alert us if a newly-added enumerator 
cannot be represented in the given underlying type.

³ a scoped enum has a fixed underlying type: int

Thanks,
Marc

-- 
Marc Mutz 
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Fabian Kosmale via Development]

I'm technically not a maintainer of either QtQml or QtQuick, but I think 
I'm qualified to chime in here:


QML has (slightly hidden in 
https://doc.qt.io/qt-6/qtqml-cppintegration-data.html#enumeration-types) 
a way to disable this behavior by setting


Q_CLASSINFO("RegisterEnumClassesUnscoped", "false")

If we had a time machine, that would certainly been a good default. 
However, toggling that behavior (or unconditionally enforcing it) would 
have a massive potential of breaking code; and currently you would only 
notice that at runtime.


What we can do in Qt 6 is to add a check in qmllint to catch scoped 
enums that are exposed to QML without setting 
RegisterEnumClassesUnscoped to false; and warn about them. Maybe even 
add a fixit to clazy/clang-tidy/other tool to convert this, and some 
additional tooling to update the QML files.


We can also add that Q_CLASSINFO for new API exposed to QML, so that 
there are no issues in that area.


And if we get this in place relatively soon, we can consider changing 
the default in Qt 7 (and removing support for accessing enums in an 
unscoped way in Qt 8).


But changing the current behavior of QML is an absolute no-go.

Regards,
Fabian

On 20.06.23 15:55, Volker Hilsheimer via Development wrote:

On 14 Jun 2023, at 14:59, Marc Mutz via Development 
 wrote:


[…]


C) scoped enums SHOULD NOT repeat (part of) an enum's type name in the
enumerators²


[…]


I have been told today that QML allows scoped C++ enums to be used
without the scope. If this is true, it should be fixed to always require
the scope, because otherwise the argument goes "but in QML, the scope
isn't visible, so a part of the enum type name must be included in the
enumerators”.


What’s the view from the QML maintainers on this particular point?

That QML allows using an enum value without scope if the C++ enum is scoped 
seems like a bug to me, although I assume that changing this will come with 
some incompatibility fallout.

Volker



--
Fabian Kosmale
Manager R&D

The Qt Company GmbH
Erich-Thilo-Str. 10
D-12489 Berlin
fabian.kosm...@qt.io
+49 1638686070
--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Volker Hilsheimer via Development]

> On 14 Jun 2023, at 14:59, Marc Mutz via Development 
>  wrote:

[…]

> C) scoped enums SHOULD NOT repeat (part of) an enum's type name in the 
> enumerators²

[…]

> I have been told today that QML allows scoped C++ enums to be used 
> without the scope. If this is true, it should be fixed to always require 
> the scope, because otherwise the argument goes "but in QML, the scope 
> isn't visible, so a part of the enum type name must be included in the 
> enumerators”.

What’s the view from the QML maintainers on this particular point? 

That QML allows using an enum value without scope if the C++ enum is scoped 
seems like a bug to me, although I assume that changing this will come with 
some incompatibility fallout.

Volker

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Friday, 16 June 2023 01:04:30 PDT Stephen Kelly wrote:
> >> https://godbolt.org/z/4EWjWhvfa
> > 
> > That's the "massive code update and can't be helped with macros" I
> > mentioned in my other email.
> 
> Are you talking about the type of the oopsLostType variable?

No, I'm talking about simply having to declare variables in the outer scope 
when using enum isn't yet available.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Stephen Kelly]

On 15/06/2023 23:34, Thiago Macieira wrote:

On Thursday, 15 June 2023 15:23:47 PDT Stephen Kelly wrote:

And, you can introduce it in a way which is source-compatible until the
user upgrades their compiler to a compiler version which implements
`using enum`:

   https://godbolt.org/z/4EWjWhvfa


That's the "massive code update and can't be helped with macros" I mentioned
in my other email.


Are you talking about the type of the oopsLostType variable? In places 
where the enum is changed as I showed, variables typed with int like 
that might be more rare than using the enum (or preferably auto). Do we 
know it's a massive porting effort?

--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Thursday, 15 June 2023 15:23:47 PDT Stephen Kelly wrote:
> And, you can introduce it in a way which is source-compatible until the
> user upgrades their compiler to a compiler version which implements
> `using enum`:
> 
>   https://godbolt.org/z/4EWjWhvfa

That's the "massive code update and can't be helped with macros" I mentioned 
in my other email.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Stephen Kelly]

On 15/06/2023 22:20, Allan Sandfeld Jensen wrote:

On Mittwoch, 14. Juni 2023 22:53:13 CEST Thiago Macieira wrote:

On Wednesday, 14 June 2023 12:49:22 PDT Allan Sandfeld Jensen wrote:

As discussed earlier. Better naming in many cases until we can depend on
C++20 in API.


There's nothing in C++20 that would allow us to design APIs differently.

You may be thinking of C++23 "using enum" feature, which is barely supported
anywhere and doesn't help us in any way I can see. It might allow us in the
future to change our existing unscoped enums to scoped, but until then
there's little we ca do.


Correct. I was referring to "using enum", which had been referred to as C++20
by Marc. It could allow "type safe" enums without scope.


It is c++20:

 https://godbolt.org/z/3nMh43jxz

And, you can introduce it in a way which is source-compatible until the 
user upgrades their compiler to a compiler version which implements 
`using enum`:


 https://godbolt.org/z/4EWjWhvfa

This looks valuable to me and in line with how Qt usually introduces 
usage of newer C++ features. I don't recall whether Qt finds a break 
like that acceptable when the user updates the compiler.


Thanks,

Stephen

--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Allan Sandfeld Jensen]

On Mittwoch, 14. Juni 2023 22:53:13 CEST Thiago Macieira wrote:
> On Wednesday, 14 June 2023 12:49:22 PDT Allan Sandfeld Jensen wrote:
> > As discussed earlier. Better naming in many cases until we can depend on
> > C++20 in API.
> 
> There's nothing in C++20 that would allow us to design APIs differently.
> 
> You may be thinking of C++23 "using enum" feature, which is barely supported
> anywhere and doesn't help us in any way I can see. It might allow us in the
> future to change our existing unscoped enums to scoped, but until then
> there's little we ca do.
> 
Correct. I was referring to "using enum", which had been referred to as C++20 
by Marc. It could allow "type safe" enums without scope. 

But yes, I don't think that is relevant right now, which is why I prefer to 
keep the cleaner API where scoping doesn't make sense.

Best regards
Allan



-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Hasselmann Mathias via Development]

Am 04.05.2023 um 15:51 schrieb Sune Vuorela:
In few cases the implicit conversion to underlying_type is kind of 
important.

Especially in the cases where the api has int and is mostly used with
enums or is somehow user extendable.

Qt::ItemDataRole is one of them that comes to mind.

switch(role) {
case Qt::UserRole+1:



I'd argue you are using role wrong. For my models I always define a 
DataRole enum. With that enum all my role related switch statements 
looks like this:


    switch (static_cast(role)) {
    }

Big advantage of explicitly casting the int to my DataRole: The compiler 
tells me if I forget to handle any of my supported roles.



Ciao
Mathias

--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Wednesday, 14 June 2023 14:26:52 PDT Giuseppe D'Angelo via Development 
wrote:
> I think this should be a completely different question than the usage of
> scoped enums in new code. For instance, I'm all for scoped enums and
> against such refactoring.

The refactoring *could* be done now, but it's a massive code update and can't 
be helped with macros. It would increase the size of most headers and 
substantially so for qnamespace.h, which might impact compilation time.

Therefore, I oppose such a change now.

But I do support a statement of intent that in Qt 7 we want to revisit this 
and change where possible. It might be a macro-enabled backwards compatible 
API, or maybe we'll be able to use "using enum" by then.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Giuseppe D'Angelo via Development]

Il 14/06/23 22:15, Volker Hilsheimer via Development ha scritto:

-1 to B from me as well.

We can allow unscoped enum as an acceptable (if explained) exception from the 
rule of using scoped enums. Otherwise we remove a tool from our toolbox, even 
if it has it’s uses in certain (increasingly rare, perhaps) situations.

More importantly, I don’t agree with the footnoted proposal of making all 
currently unscoped enums scoped in Qt 7. Such a change would cause a massive 
porting effort (tool or not), with zero value for users. There might be 
exceptions where we have genuine issues from certain enums being unscoped, we 
can fix those with appropriate porting aids and compatibility wrappers/aliases.


I think this should be a completely different question than the usage of 
scoped enums in new code. For instance, I'm all for scoped enums and 
against such refactoring.


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: Firma crittografica S/MIME
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Wednesday, 14 June 2023 12:49:22 PDT Allan Sandfeld Jensen wrote:
> As discussed earlier. Better naming in many cases until we can depend on
> C++20 in API.

There's nothing in C++20 that would allow us to design APIs differently.

You may be thinking of C++23 "using enum" feature, which is barely supported 
anywhere and doesn't help us in any way I can see. It might allow us in the 
future to change our existing unscoped enums to scoped, but until then there's 
little we ca do.

So this question is strictly a C++11 scoped enum one.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Volker Hilsheimer via Development]

+1 to A and C.

> On 14 Jun 2023, at 21:49, Allan Sandfeld Jensen  wrote:
> 
> On Mittwoch, 14. Juni 2023 17:48:27 CEST Thiago Macieira wrote:
>> On Wednesday, 14 June 2023 08:35:16 PDT Marc Mutz via Development wrote:
>> B) new enums MUST be scoped, also when nested in classes¹²
> 
> -1 Disagree
 
 -1 Disagree
>>> 
>>> Ok. But _why_? (Q to both)
>> 
>> I'm inclined to agree with (B), so I'd like to understand the objections.
> 
> As discussed earlier. Better naming in many cases until we can depend on
> C++20 in API. I disagree with designing API for standards we are not yet 
> allowed to use. And there are a few rare cases with flags or other composite 
> value types, where the implicit casting is desirable. I wouldn't mind saying 
> scoped enums are the preferred default, and any unscoped enum needs to be 
> justified in the commit message, but I would hate to ban them out right. 
> 
> Best regards
> Allan


-1 to B from me as well.

We can allow unscoped enum as an acceptable (if explained) exception from the 
rule of using scoped enums. Otherwise we remove a tool from our toolbox, even 
if it has it’s uses in certain (increasingly rare, perhaps) situations.

More importantly, I don’t agree with the footnoted proposal of making all 
currently unscoped enums scoped in Qt 7. Such a change would cause a massive 
porting effort (tool or not), with zero value for users. There might be 
exceptions where we have genuine issues from certain enums being unscoped, we 
can fix those with appropriate porting aids and compatibility wrappers/aliases.

Volker

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Allan Sandfeld Jensen]

On Mittwoch, 14. Juni 2023 17:48:27 CEST Thiago Macieira wrote:
> On Wednesday, 14 June 2023 08:35:16 PDT Marc Mutz via Development wrote:
> > >>> B) new enums MUST be scoped, also when nested in classes¹²
> > >> 
> > >> -1 Disagree
> > > 
> > > -1 Disagree
> > 
> > Ok. But _why_? (Q to both)
> 
> I'm inclined to agree with (B), so I'd like to understand the objections.

As discussed earlier. Better naming in many cases until we can depend on
C++20 in API. I disagree with designing API for standards we are not yet 
allowed to use. And there are a few rare cases with flags or other composite 
value types, where the implicit casting is desirable. I wouldn't mind saying 
scoped enums are the preferred default, and any unscoped enum needs to be 
justified in the commit message, but I would hate to ban them out right. 

Best regards
Allan




-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Tor Arne Vestbø via Development]

> On 14 Jun 2023, at 17:48, Thiago Macieira  wrote:
> 
> On Wednesday, 14 June 2023 08:35:16 PDT Marc Mutz via Development wrote:
> B) new enums MUST be scoped, also when nested in classes¹²
 
 -1 Disagree
>>> 
>>> -1 Disagree
>> 
>> Ok. But _why_? (Q to both)
> 
> I'm inclined to agree with (B), so I'd like to understand the objections.

This position has been explained ad nauseam. Please go back and read earlier 
emails in this thread.

Cheers,
Tor Arne
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Wednesday, 14 June 2023 08:35:16 PDT Marc Mutz via Development wrote:
> >>> B) new enums MUST be scoped, also when nested in classes¹²
> >> 
> >> -1 Disagree
> > 
> > -1 Disagree
> 
> Ok. But _why_? (Q to both)

I'm inclined to agree with (B), so I'd like to understand the objections.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Marc Mutz via Development]

On 14.06.23 16:33, Tor Arne Vestbø via Development wrote:
>> On 14 Jun 2023, at 16:20, Allan Sandfeld Jensen  wrote:
[...]
>>> B) new enums MUST be scoped, also when nested in classes¹²
>> -1 Disagree
> 
> -1 Disagree

Ok. But _why_? (Q to both)

>>
>>>
>>> C) scoped enums SHOULD NOT repeat (part of) an enum's type name in the
>>> enumerators²
>>>
>> +1 Agree, and if you find you do repeat the type name in an unscoped 
>> enum it
>> probably should be scoped. But isn't this already in our style guide?
> 
> +1 Agree, and yes, it’s already in our style guide.

It's not really, no. The wording is that repeating the name isn't 
_necessary_. That's the kind of wording that will get a discussion going 
over every new enum. It should say you shouldn't repeat the name, unless 
there's a reason (and QML is not a reason, otherwise it's not an 
exception anymore).

-- 
Marc Mutz 
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Tor Arne Vestbø via Development]

On 14 Jun 2023, at 16:20, Allan Sandfeld Jensen  wrote:

On Mittwoch, 14. Juni 2023 14:59:40 CEST Marc Mutz via Development wrote:
On 02.05.23 10:58, Volker Hilsheimer via Development wrote:
During the header review, but also in API discussions leading up to it, we
had a few cases where it would have helped if we had clearer guidelines
about when to use scoped enums, and when not.
Was there some consensus here? We're discussing this _again_ in the 6.6
review...

Let me propose the following, separate issues, so we have something
concrete to +1 or -1:

[All capitalized words have the meaning of IETF RFCs]

A) new enums MUST have an explicit underlying type¹²
+1 Sure

+1 Sure



B) new enums MUST be scoped, also when nested in classes¹²
-1 Disagree

-1 Disagree



C) scoped enums SHOULD NOT repeat (part of) an enum's type name in the
enumerators²

+1 Agree, and if you find you do repeat the type name in an unscoped enum it
probably should be scoped. But isn't this already in our style guide?

+1 Agree, and yes, it’s already in our style guide.

Cheers,
Tor Arne

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Allan Sandfeld Jensen]

On Mittwoch, 14. Juni 2023 14:59:40 CEST Marc Mutz via Development wrote:
> On 02.05.23 10:58, Volker Hilsheimer via Development wrote:
> > During the header review, but also in API discussions leading up to it, we
> > had a few cases where it would have helped if we had clearer guidelines
> > about when to use scoped enums, and when not.
> Was there some consensus here? We're discussing this _again_ in the 6.6
> review...
> 
> Let me propose the following, separate issues, so we have something
> concrete to +1 or -1:
> 
> [All capitalized words have the meaning of IETF RFCs]
> 
> A) new enums MUST have an explicit underlying type¹²
+1 Sure

> 
> B) new enums MUST be scoped, also when nested in classes¹²
-1 Disagree

> 
> C) scoped enums SHOULD NOT repeat (part of) an enum's type name in the
> enumerators²
> 
+1 Agree, and if you find you do repeat the type name in an unscoped enum it 
probably should be scoped. But isn't this already in our style guide?

Best regards
Allan



-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Marc Mutz via Development]

On 02.05.23 10:58, Volker Hilsheimer via Development wrote:
> During the header review, but also in API discussions leading up to it, we 
> had a few cases where it would have helped if we had clearer guidelines about 
> when to use scoped enums, and when not.

Was there some consensus here? We're discussing this _again_ in the 6.6 
review...

Let me propose the following, separate issues, so we have something 
concrete to +1 or -1:

[All capitalized words have the meaning of IETF RFCs]

A) new enums MUST have an explicit underlying type¹²

For unscoped enums, the compiler otherwise picks one, possibly resulting 
in BiC when new addtions change the underlying type or otherwise just 
warnings because one compiler uses a signed and the other an unsigned 
type (most recent exmaple: QTBUG-113792). For scoped enums, the type is 
int, but probably not always, and why require the reader of the code to 
know the C++ rules when we can make it explicit?

B) new enums MUST be scoped, also when nested in classes¹²

Type safety > verbosity. Qt has never preferred brevity over verbosity 
when it comes to readability, and while the use of short identifiers 
makes code often more readable than using long ones, C++20's `using 
enum` feature empowers users to choose between brevity and verbosity on 
a per-use basis. Since we should be designing for the future and not the 
past, this removes the major objection for scoped enums. C++17 doesn't 
matter. If we really want leaking, we can use constexpr variables of 
scoped enum type in lieu of enumerators.

C) scoped enums SHOULD NOT repeat (part of) an enum's type name in the 
enumerators²

This was a work-around from the times of C/C++98 when you could neither 
scope the value of an enumeration nor prevent the leakage of enumerator 
names into the enclosing scope. We have both now in C++11: any 
enumerator can be scoped and scoped enums don't leak the name into the 
enclosing scope anymore.

I cannot rule out that sometimes some part of the enum's type may make 
sense in an enumerator's name, but not consistently in all of them just 
because one of them needs it etc, so this is a SHOULD, not a MUST.

I have been told today that QML allows scoped C++ enums to be used 
without the scope. If this is true, it should be fixed to always require 
the scope, because otherwise the argument goes "but in QML, the scope 
isn't visible, so a part of the enum type name must be included in the 
enumerators".

¹ except when C compatibility is required
² applies to all enums come Qt 7

It would be good if we could have clarity on A-C before we finish up the 
6.6 API review.

Thanks,
Marc

-- 
Marc Mutz 
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Monday, 8 May 2023 00:21:32 PDT Sune Vuorela wrote:
> How would you do the extensions (e.g. user roles or user events)
> if you convert to enums ?

Still with the enum, but you need to somewhere write extra code to cast that 
new number to the proper type. That's all.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Sune Vuorela]

On 2023-05-04, Marc Mutz via Development  wrote:
> So, enum-backed APIs taking int will have to be ported to take the enum 
> instead. On the plus side, you get type-richer and safer APIs.

How would you do the extensions (e.g. user roles or user events) 
if you convert to enums ?

/Sune

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Friday, 5 May 2023 03:49:58 PDT Allan Sandfeld Jensen wrote:
> Wasn't there a new C++ proposal for decoupling the two separate features of
> enum class?

It's probably the using enum, which is C++20 and requires GCC 11 or Clang 13.
https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1099r5.html

It does allow us to replace enums inside a class with an enum class and mostly 
retain source compatibility -- breaking only where regular enums decay to 
their underlying types.

But it doesn't help us in the other direction, which is to *use* the scope for 
flags. I tried several different things after posting the idea last night, but 
I 
haven't found a way to make this work:

QIODevice::OpenMode mode = QIODevice::OpenMode::ReadOnly;

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Allan Sandfeld Jensen]

On Mittwoch, 3. Mai 2023 19:40:18 CEST Marc Mutz via Development wrote:
> On 03.05.23 19:22, Thiago Macieira wrote:
> > On Wednesday, 3 May 2023 09:40:42 PDT Giuseppe D'Angelo via Development 
wrote:
> >>   To me it's a no brainer: any new enumeration
> >> 
> >> added to Qt shall be an enum class.
> > 
> > I'd say that any new enumeration in the Qt namespace should be enum class,
> > but enums in classes may not be so if they're sufficiently descriptive
> > already.
> That's the wording we currently have, and I have two problems with that:
> 
> - it's subjective, which means we get to quarrel over every class-scope
> enum anew
> - it completely ignores the point that scoped enums don't implicitly
> convert to underlying_type, which is a very welcome subtraction from
> C/C++'s infamous implicit conversion mess
> 
> So if it's a vote: +1 for all new enums being scoped and +1 for all old
> enums being made scoped come Qt 7.
> 
I am not sure I want the name scope in all cases QEvent::Timer is descriptive 
enough, and would be improved by being QEvent::Type::Timer. With new classes 
in Qt6, I have generally preferred using scoped enums, but found several 
instances were it didn't make sense.  For instance using QColorSpace::SRgb and 
QColorSpace::AdobeRgb for predefined color-spaces, where all other enums in 
QColorSpace are scoped.

Wasn't there a new C++ proposal for decoupling the two separate features of 
enum class?

Best regards
Allan


-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Thursday, 4 May 2023 22:48:44 PDT Thiago Macieira wrote:
> On Thursday, 4 May 2023 22:28:44 PDT Thiago Macieira wrote:
> > But for those that use a very name, the API becomes cumbersome:
> >   Qt::Alignment al = Qt::AlignmentFlag::Left;
> > 
> > Can we do better? With C++20 using enum (GCC 11, Clang 13, so not in my
> > proposal) we could easily.
> 
> Actually, we can leave that as an optional feature for GCC 10 and Clang 10,
> if we choose those as our minima. We wouldn't be able to use the used
> enumerations in our code until the feature became mandatory, but users
> whose compilers do support the feature could use it.
> 
> https://codereview.qt-project.org/c/qt/qtbase/+/476084

Scratch that. This doesn't work and I don't know why:
https://gcc.godbolt.org/z/6jf7Ebecq

Looks like the using enum feature is not very useful for us. Back to the 
drawing board for scoped flags.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Thursday, 4 May 2023 22:28:44 PDT Thiago Macieira wrote:
> But for those that use a very name, the API becomes cumbersome:
> 
>   Qt::Alignment al = Qt::AlignmentFlag::Left;
> 
> Can we do better? With C++20 using enum (GCC 11, Clang 13, so not in my
> proposal) we could easily.

Actually, we can leave that as an optional feature for GCC 10 and Clang 10, if 
we choose those as our minima. We wouldn't be able to use the used 
enumerations in our code until the feature became mandatory, but users whose 
compilers do support the feature could use it.

https://codereview.qt-project.org/c/qt/qtbase/+/476084

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Thursday, 4 May 2023 21:43:01 PDT Marc Mutz via Development wrote:
> Since the rename is specific to the enum at hand, there's no hope that
> such tooling exists today. However, simple semantic symbol replacement
> is an easy thing to implement in clang-tidy, yes. That could be
> accompanied by Thiago's memory_order trick and Q_DECL_DEPRECATED.

This should be doable right now for the Qt namespace.

But I don't think it should be automated. Instead, we need to put some thought 
into the new names. For the majority of them, we can probably remove the noun 
that is part of the name (Qt::MouseButton::LeftButton → 
Qt::MouseButton::Left), but sometimes the change isn't obvious. We can also fix 
historical mistakes, like the colour names in Qt::GlobalColor being lowercase. 
Some of them won't work for other reasons, like Qt::Key_I can't become 
Qt::Key::I because the identifier I is defined in  as a macro for 
the 
imaginary unit[1] (this shouldn't affect C++, but broken implementations 
exist).

There are also enums that may serve multiple purposes, like the enumerator 
Qt::KeepEmptyParts. Right now, it's part of SplitBehavior, but it could just 
as well be used for joining. Or not, see [2] for discussion.

And there are all the flags. For the vast majority of them, the only documented 
name is the QFlags typedef. For those whose QFlags typedef is just the plural 
of the enum, code like this is probably acceptable:

  Qt::Edges edges = Qt::Edge::Top | Qt::Edge::Left;

But for those that use a very name, the API becomes cumbersome:

  Qt::Alignment al = Qt::AlignmentFlag::Left;

Can we do better? With C++20 using enum (GCC 11, Clang 13, so not in my 
proposal) we could easily.

[1] https://en.cppreference.com/w/c/numeric/complex/I
[2] https://codereview.qt-project.org/c/qt/qtbase/+/471246?usp=email

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Marc Mutz via Development]

On 04.05.23 19:35, André Somers wrote:
[...]
> Other fallout would be that currently A, B, and C will most often 
> include E in their name. That makes for the code becoming
> 
> E::EA, E::EB, E::EC or E::AE, E::BE, E::CE. I don't like that. Do you 
> think there also is tooling to go to a renamed version w/o the enum 
> name? Or would it be feasible to add such tooling?

Since the rename is specific to the enum at hand, there's no hope that 
such tooling exists today. However, simple semantic symbol replacement 
is an easy thing to implement in clang-tidy, yes. That could be 
accompanied by Thiago's memory_order trick and Q_DECL_DEPRECATED.

Thanks,
Marc

-- 
Marc Mutz 
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[André Somers]

On 03/05/2023 21:42, Marc Mutz via Development wrote:

On 03.05.23 20:06, A. Pönitz wrote:

My main problem with enum classes _in Qt_ is that it is inconsistent
with what has been there traditionally. It is simply no fun to guess
what "style" some enum is (and sure, Peppe has a point when hinting that
the naming scheme wasn't applied uniformly in the pre-past either...)

There is a pretty straight-forward migration path (and I'm sure that
clang-tidy has an automatic transformation already):

For amy unscoped

  enum E { A, B, C, };

you can, since C++11, write

  E::A, E::B, E::C

This rewrite is an automatable task, and, once done, we can make E
scoped, and just have to deal with (desired) fallout of the missing
implicit conversion to underlying_type.

So if your problem is consistency, then just scope the unscoped
enumerators in your code as if they were scoped.


Other fallout would be that currently A, B, and C will most often 
include E in their name. That makes for the code becoming


E::EA, E::EB, E::EC or E::AE, E::BE, E::CE. I don't like that. Do you 
think there also is tooling to go to a renamed version w/o the enum 
name? Or would it be feasible to add such tooling?


Cheers,

André



Thanks,
Marc


--
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[André Somers]

On 04/05/2023 15:51, Sune Vuorela wrote:

On 2023-05-04, Marc Mutz via Development  wrote:

that keeps unported code running. The main issue isn't the scoping, the
main issue will be the missing implicit conversion to underlying_type.

In few cases the implicit conversion to underlying_type is kind of important.

Especially in the cases where the api has int and is mostly used with
enums or is somehow user extendable.

Qt::ItemDataRole is one of them that comes to mind.

switch(role) {
case Qt::UserRole+1:



First of all, the use of Qt::UserRole+1 isn't really good practice. 
Define your roles in a scoped enum. For this use case, we have been 
using this little trick:


// Tool to convert class enum value to underlying type for easier use
template 
constexpr typename std::underlying_type::type operator+(const E &e)
{
return static_cast::type>(e);
}

Now, we can write the switch like this:

switch (role) {
   case +Roles::Name: //...
   case +Roles::Age: //...

Of course, you can also do:

switch (static_cast(int)) {
   case Roles::Name: //...
   case Roles::Age: //...

But AFAIK, now you need to make sure the int value actually is in the 
enum first to make that safe.


Cheers,

André
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Jaroslaw Kobus via Development]

>> On 4 May 2023, at 17:34, Marc Mutz via Development 
>>  wrote:
>>
>> On 04.05.23 15:38, Volker Hilsheimer via Development wrote:
>>> Should we have Qt::TextLayout::Horizontal and Qt::Layout::Horizontal? Or 
>>> QSlider::Orientation::Horizontal?
>>
>> Without looking at the docs, tell me what QSplitterHandle::orientation()
>> means :)
>
> The same that it would mean if it would return Qt::Orientation::Horizontal or 
> Qt::HorizontalOrientation :)
>
> I’m guessing: whether the handle gets dragged horizontally or vertically, ie 
> the opposite of what one would expect (whether the handle is v horizontal or 
> vertical line). In which case the problem is the name of the property not of 
> the enum type.

I remember that couple of years ago Eike did a pool on how name actions 
regarding horizontal and vertical splitting inside QtCreator. So, for some, the 
"horizontal" means that they want to see a horizontal splitter bar after the 
split, and for others it means that they want to see horizontally arranged 
editors (from left to right). The outcome was that we have now "Split" and 
"Split Side by Side" actions.

Jarek
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Giuseppe D'Angelo via Development]

Il 04/05/23 09:10, Marc Mutz via Development ha scritto:

With the same trick that C++20 did for std::memory_order?

That's an additional step we can take, but if clang-tidy has a
modernize-scope-enums (or we could write it), then it would be
preferable to just automatically port all users instead of writing code
that keeps unported code running. The main issue isn't the scoping, the
main issue will be the missing implicit conversion to underlying_type.


A few remarks:

* I think it's pretty optimistic to assume that people can/will use 
clang-based tooling on their codebases.


* This doesn't cope with an unspecified amount of other code -- thinking 
of .ui files, DBus XML interfaces, other serializations (QVariant?), 
etc. -- where the enumerators are currently written unscoped. We'd need 
a bunch of extra tools to fix all of that.


* Something doable in Qt 6 already: we need a QFlagsV2 that works across 
multiple enumerations (and that can use 8/16/32/64 bits, while at it), 
because we *still* have int-based APIs where one has to mix values from 
two or more enumerators.



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: Firma crittografica S/MIME
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Volker Hilsheimer via Development]

> On 4 May 2023, at 17:34, Marc Mutz via Development 
>  wrote:
> 
> On 04.05.23 15:38, Volker Hilsheimer via Development wrote:
>> Should we have Qt::TextLayout::Horizontal and Qt::Layout::Horizontal? Or 
>> QSlider::Orientation::Horizontal?
> 
> Without looking at the docs, tell me what QSplitterHandle::orientation() 
> means :)

The same that it would mean if it would return Qt::Orientation::Horizontal or 
Qt::HorizontalOrientation :)

I’m guessing: whether the handle gets dragged horizontally or vertically, ie 
the opposite of what one would expect (whether the handle is v horizontal or 
vertical line). In which case the problem is the name of the property not of 
the enum type.

Volker

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Giuseppe D'Angelo via Development]

Il 04/05/23 15:51, Sune Vuorela ha scritto:

On 2023-05-04, Marc Mutz via Development  wrote:

that keeps unported code running. The main issue isn't the scoping, the
main issue will be the missing implicit conversion to underlying_type.

In few cases the implicit conversion to underlying_type is kind of important.

Especially in the cases where the api has int and is mostly used with
enums or is somehow user extendable.

Qt::ItemDataRole is one of them that comes to mind.

switch(role) {
case Qt::UserRole+1:


QEvent::Type is another one where one registerEventType, recieves an int
and then force-cast it to QEvent::Type and still compares back to that
int in other places.


There are definitely more.


There's little reason why registerEventType returns `int` and not 
QEvent::Type, by the way. Model roles could become scoped enumerations, 
which can be explicitly constructed from integers (all of this just to 
retain the switch()-ability -- otherwise a model role should be 
represented by a wrapper type around integers. Certainly not be kept as 
a plain int).


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: Firma crittografica S/MIME
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Marc Mutz via Development]

On 04.05.23 15:38, Volker Hilsheimer via Development wrote:
> Should we have Qt::TextLayout::Horizontal and Qt::Layout::Horizontal? Or 
> QSlider::Orientation::Horizontal?

Without looking at the docs, tell me what QSplitterHandle::orientation() 
means :)

-- 
Marc Mutz 
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Marc Mutz via Development]

On 04.05.23 15:51, Sune Vuorela wrote:
> On 2023-05-04, Marc Mutz via Development  wrote:
>> that keeps unported code running. The main issue isn't the scoping, the
>> main issue will be the missing implicit conversion to underlying_type.
> 
> In few cases the implicit conversion to underlying_type is kind of important.
> 
> Especially in the cases where the api has int and is mostly used with
> enums or is somehow user extendable.
> 
> Qt::ItemDataRole is one of them that comes to mind.
> 
> switch(role) {
> case Qt::UserRole+1:
> 
> 
> QEvent::Type is another one where one registerEventType, recieves an int
> and then force-cast it to QEvent::Type and still compares back to that
> int in other places.

The int is the problem, not the enum. With C++17, scoped enums have a 
kind of explicit ctor from underlying_type, so at least that direction 
is reasonably convenient. For the other direction, there's 
std::to_underlying/qToUndelying().

So, enum-backed APIs taking int will have to be ported to take the enum 
instead. On the plus side, you get type-richer and safer APIs.

Thanks,
Marc

-- 
Marc Mutz 
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Thursday, 4 May 2023 00:58:52 PDT Marco Bubke via Development wrote:
> This is introducing dependencies on code which makes dependency breaking
> much harder. I very often need an enumeration in an interface but not the
> class itself. There are ways to get around that but it makes TDD harder if
> Qt is involved.

That's a good point, but it's a bigger change to our style guide than "to 
class or not to class". Requesting that we design our enumerations outside of 
any class/struct is a big change.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Sune Vuorela]

On 2023-05-04, Marc Mutz via Development  wrote:
> that keeps unported code running. The main issue isn't the scoping, the 
> main issue will be the missing implicit conversion to underlying_type.

In few cases the implicit conversion to underlying_type is kind of important.

Especially in the cases where the api has int and is mostly used with
enums or is somehow user extendable.

Qt::ItemDataRole is one of them that comes to mind.

switch(role) {
   case Qt::UserRole+1:
   

QEvent::Type is another one where one registerEventType, recieves an int
and then force-cast it to QEvent::Type and still compares back to that
int in other places.


There are definitely more.

/Sune

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Volker Hilsheimer via Development]

> On 3 May 2023, at 18:40, Giuseppe D'Angelo via Development 
>  wrote:
>> But sometimes it’s also creating too much verbosity to use a scoped enum 
>> (ie. Qt::Orientation::Horizontal would perhaps not be an improvement).
> 
> I wouldn't consider this tiny bit of extra verbosity a huge impediment. Note 
> that Qt::Horizontal is violating the API naming guidelines. It should've been 
> called Qt::HorizontalOrientation. How is that now better than 
> Qt::Orientation::Horizontal?
> 
> No, Qt::Horizontal isn't "unambiguous" so it can't be non-qualified. Does it 
> refer to what? Text alignment? Text direction? Layout direction? (Hint: none 
> of these.)


Some concepts are abstract enough to be ubiquitous. On/Off, true/false. 
Horizontal and Vertical are IMHO implicitly clear. What it refers to is not 
clear anyway unless you see the code that uses the enum. I can make a slider or 
a layout or a text horizontal or vertical, and it’s IMHO obvious what calls to

textLayout->setOrientation(Qt::Horizontal);
slider->setOrientation(Qt::Vertical);

are doing. The word “Orientation” in the enum itself adds no value.

Should we have Qt::TextLayout::Horizontal and Qt::Layout::Horizontal? Or 
QSlider::Orientation::Horizontal?

I do think that these are the exceptions though.


Cheers,
Volker

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Marco Bubke via Development]

Hi Thiago

This is introducing dependencies on code which makes dependency breaking much 
harder. I very often need an enumeration in an interface but not the class 
itself. There are ways to get around that but it makes TDD harder if Qt is 
involved.


From: Development  on behalf of Thiago 
Macieira 
Sent: Thursday, May 4, 2023 0:17
To: development@qt-project.org 
Subject: Re: [Development] API style guide: scoped enum or not?

On Wednesday, 3 May 2023 10:51:18 PDT Jaroslaw Kobus via Development wrote:
> "enum class" has one advantage over "enum" inside a "class" : you may
> forward declare the "enum class", while the other not. That's quite often
> case that your header must include the other header just because you use
> the "enum" in "class" in your API and nothing more.

Hello Jarek

That's fair, but that requires a separate scope from the class itself. That
alone may be a reason not to do so, and instead just declare the enum inside
the class, as our current practice dictates, with the choice of plain enum or
enum class.
--
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Marc Mutz via Development]

On 04.05.23 00:18, Thiago Macieira wrote:
> On Wednesday, 3 May 2023 10:40:18 PDT Marc Mutz via Development wrote:
>> So if it's a vote: +1 for all new enums being scoped and +1 for all old
>> enums being made scoped come Qt 7.
> 
> With the same trick that C++20 did for std::memory_order?

That's an additional step we can take, but if clang-tidy has a 
modernize-scope-enums (or we could write it), then it would be 
preferable to just automatically port all users instead of writing code 
that keeps unported code running. The main issue isn't the scoping, the 
main issue will be the missing implicit conversion to underlying_type.

-- 
Marc Mutz 
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Wednesday, 3 May 2023 10:40:18 PDT Marc Mutz via Development wrote:
> So if it's a vote: +1 for all new enums being scoped and +1 for all old
> enums being made scoped come Qt 7.

With the same trick that C++20 did for std::memory_order?

  enum class memory_order : int
{
  relaxed,
  consume,
  acquire,
  release,
  acq_rel,
  seq_cst
};

  inline constexpr memory_order memory_order_relaxed = memory_order::relaxed;
  inline constexpr memory_order memory_order_consume = memory_order::consume;
  inline constexpr memory_order memory_order_acquire = memory_order::acquire;
  inline constexpr memory_order memory_order_release = memory_order::release;
  inline constexpr memory_order memory_order_acq_rel = memory_order::acq_rel;
  inline constexpr memory_order memory_order_seq_cst = memory_order::seq_cst;


-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Wednesday, 3 May 2023 10:51:18 PDT Jaroslaw Kobus via Development wrote:
> "enum class" has one advantage over "enum" inside a "class" : you may
> forward declare the "enum class", while the other not. That's quite often
> case that your header must include the other header just because you use
> the "enum" in "class" in your API and nothing more.

Hello Jarek

That's fair, but that requires a separate scope from the class itself. That 
alone may be a reason not to do so, and instead just declare the enum inside 
the class, as our current practice dictates, with the choice of plain enum or 
enum class.
-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Marc Mutz via Development]

On 03.05.23 20:06, A. Pönitz wrote:
> My main problem with enum classes _in Qt_ is that it is inconsistent
> with what has been there traditionally. It is simply no fun to guess
> what "style" some enum is (and sure, Peppe has a point when hinting that
> the naming scheme wasn't applied uniformly in the pre-past either...)

There is a pretty straight-forward migration path (and I'm sure that 
clang-tidy has an automatic transformation already):

For amy unscoped

 enum E { A, B, C, };

you can, since C++11, write

 E::A, E::B, E::C

This rewrite is an automatable task, and, once done, we can make E 
scoped, and just have to deal with (desired) fallout of the missing 
implicit conversion to underlying_type.

So if your problem is consistency, then just scope the unscoped 
enumerators in your code as if they were scoped.

Thanks,
Marc

-- 
Marc Mutz 
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[A . Pönitz]

[re-ordered]

On Wed, May 03, 2023 at 05:32:46PM +, Axel Spoerl via Development
wrote:
> > On 3 May 2023, at 18:42, Giuseppe D'Angelo via Development
> >  wrote:
> > 
> > 02/05/23 10:58, Volker Hilsheimer via Development ha
> > scritto:
> >> During the header review, but also in API discussions leading up to
> >> it, we had a few cases where it would have helped if we had clearer
> >> guidelines about when to use scoped enums, and when not.  Scoped
> >> enums have some clear technical advantages (such as better type
> >> safety, thanks to no implicit conversion to int). And they
> >> sometimes result in better APIs when enum values don’t have to
> >> repeat the enum’s name in order to be clear.
> > 
> > Should we vote on this? To me it's a no brainer: any new enumeration
> > added to Qt shall be an enum class.
> > 
> >> But sometimes it’s also creating too much verbosity to use a scoped
> >> enum (ie. Qt::Orientation::Horizontal would perhaps not be an
> >> improvement).
> > 
> > I wouldn't consider this tiny bit of extra verbosity a huge
> > impediment. Note that Qt::Horizontal is violating the API naming
> > guidelines. It should've been called Qt::HorizontalOrientation. How
> > is that now better than Qt::Orientation::Horizontal?
> > 
> > No, Qt::Horizontal isn't "unambiguous" so it can't be non-qualified.
> > Does it refer to what? Text alignment? Text direction? Layout
> > direction? (Hint: none of these.)
> > 
> > The extra verbosity e.g. in switches can be tamed; one more reason
> > to upgrade to C++20:
> > 
> > https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1099r5.html
>
[...]
>
> +1 for every new enum added being an enum class. Exceptions to be
> approved here case by case. 

My main problem with enum classes _in Qt_ is that it is inconsistent
with what has been there traditionally. It is simply no fun to guess
what "style" some enum is (and sure, Peppe has a point when hinting that
the naming scheme wasn't applied uniformly in the pre-past either...)

I know uniform API isn't exactly en vogue anymore, but in this
particular case here I wonder whether it would be possible with
reasonable effort to go all-in on enum classes by offering "equivalent"
enum classes to non-class enums and e.g. suitable overloads in core API
so that I would have "one way to do it" again.

Opinions?

Andre'
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Jaroslaw Kobus via Development]

"enum class" has one advantage over "enum" inside a "class" : you may forward 
declare the "enum class", while the other not. That's quite often case that 
your header must include the other header just because you use the "enum" in 
"class" in your API and nothing more.

Jarek


From: Development  on behalf of Tor Arne 
Vestbø via Development 
Sent: Wednesday, May 3, 2023 7:39 PM
To: Macieira, Thiago
Cc: development@qt-project.org
Subject: Re: [Development] API style guide: scoped enum or not?



On 3 May 2023, at 19:22, Thiago Macieira  wrote:

I'd say that any new enumeration in the Qt namespace should be enum class, but
enums in classes may not be so if they're sufficiently descriptive already.

Agreed, and this is also what our current API design guide says:

<https://wiki.qt.io/API_Design_Principles#Naming_Enum_Types_and_Values>
API Design Principles - Qt 
Wiki<https://wiki.qt.io/API_Design_Principles#Naming_Enum_Types_and_Values>
wiki.qt.io<https://wiki.qt.io/API_Design_Principles#Naming_Enum_Types_and_Values>
[favicon.ico]<https://wiki.qt.io/API_Design_Principles#Naming_Enum_Types_and_Values>


tor arne
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Marc Mutz via Development]

On 03.05.23 19:22, Thiago Macieira wrote:
> On Wednesday, 3 May 2023 09:40:42 PDT Giuseppe D'Angelo via Development wrote:
>>   To me it's a no brainer: any new enumeration
>> added to Qt shall be an enum class.
> 
> I'd say that any new enumeration in the Qt namespace should be enum class, but
> enums in classes may not be so if they're sufficiently descriptive already.

That's the wording we currently have, and I have two problems with that:

- it's subjective, which means we get to quarrel over every class-scope 
enum anew
- it completely ignores the point that scoped enums don't implicitly 
convert to underlying_type, which is a very welcome subtraction from 
C/C++'s infamous implicit conversion mess

So if it's a vote: +1 for all new enums being scoped and +1 for all old 
enums being made scoped come Qt 7.

Thanks,
Marc

-- 
Marc Mutz 
Principal Software Engineer

The Qt Company
Erich-Thilo-Str. 10 12489
Berlin, Germany
www.qt.io

Geschäftsführer: Mika Pälsi, Juha Varelius, Jouni Lintunen
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht Charlottenburg,
HRB 144331 B

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Tor Arne Vestbø via Development]

On 3 May 2023, at 19:22, Thiago Macieira  wrote:

I'd say that any new enumeration in the Qt namespace should be enum class, but
enums in classes may not be so if they're sufficiently descriptive already.

Agreed, and this is also what our current API design guide says:


API Design Principles - Qt 
Wiki
wiki.qt.io
[favicon.ico]


tor arne
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Tor Arne Vestbø via Development]

On 3 May 2023, at 18:40, Giuseppe D'Angelo via Development 
 wrote:

Il 02/05/23 10:58, Volker Hilsheimer via Development ha scritto:
During the header review, but also in API discussions leading up to it, we had 
a few cases where it would have helped if we had clearer guidelines about when 
to use scoped enums, and when not.
Scoped enums have some clear technical advantages (such as better type safety, 
thanks to no implicit conversion to int). And they sometimes result in better 
APIs when enum values don’t have to repeat the enum’s name in order to be clear.

Should we vote on this? To me it's a no brainer: any new enumeration added to 
Qt shall be an enum class.

But sometimes it’s also creating too much verbosity to use a scoped enum (ie. 
Qt::Orientation::Horizontal would perhaps not be an improvement).

I wouldn't consider this tiny bit of extra verbosity a huge impediment. Note 
that Qt::Horizontal is violating the API naming guidelines. It should've been 
called Qt::HorizontalOrientation. How is that now better than 
Qt::Orientation::Horizontal?

No, Qt::Horizontal isn't "unambiguous" so it can't be non-qualified. Does it 
refer to what? Text alignment? Text direction? Layout direction? (Hint: none of 
these.)

These are all straw men.

I’ll quote directly from 
https://wiki.qt.io/API_Design_Principles#Naming_Enum_Types_and_Values
Naming Enum Types and Values

The guiding principle is to avoid name clashes between enum values and to 
ensure readability code with reasonable verbosity.

Enums in Qt/global namespace

New enums in the Qt namespace should always use scoped/strong enumerators by 
default. The scoping/strong typing ensures that there is no conflict if the 
same enum value name is used multiple times:

 namespace Qt
 {
   enum class Color {
 Blue,
 Orange,
 Yellow
   };

   enum class FavoriteColor {
 Yellow,
 Orange
   };
 }

 Color yellow = Qt::Color::Yellow;
 FavoriteColor yellow2 = Qt::FavoriteColor::Yellow;
 yellow2 = Qt::Orange; // error


When using scoped enums additional naming rules (repeating of enum type name 
inside enum value name) for are not necessary.

Enums in classes

Enums inside a class do not have the same problem of names clashing, as they 
are already namespaced within the class.

There are still reasons to prefer scoped enums inside classes, but this should 
be decided on a case by case basis.

If the enum values have a clear relation to the parent class, prefer un-scoped 
enums:

 class TouchPoint
 {
   enum State {
Pressed,
Held,
Released
   };
};

// The context is clear when used outside the class
if (point.state() == TouchPoint::Pressed)
   ...

// As well as when used inside it
if (state() == Pressed)
   ...


Using scoped enums in this case would add redundant line noise:

if (point.state() == TouchPoint::State::Pressed)
   ...
if (state() == State::Pressed)
   ...


Note that the context where the enum is used, such as the name of the getter 
that returns the enum value, might be enough information to make a scoped enum 
redundant.

If the enum values do not have a natural relation to the class name, prefer 
scoped enums, e.g.:

 class QSslCertificate
 {
   enum class PatternSyntax {
RegularExpression,
Wildcard,
FixedString
   };
};

if (syntax == PatternSyntax::Wildcard)
  ...


Another option to avoid the name clash instead of scoped/strong enums is to 
embedded the enum type name into each enum value. This method was extensively 
used in Qt 4 before scoped/strong enums were available.

 class Widget
 {
  enum Corner {
   TopLeftCorner,
   BottomRightCorner,
…
  };
 };

 tabWidget->setCornerWidget(widget, Widget::TopLeftCorner);
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Axel Spoerl via Development]

+1 for every new enum added being an enum class. Exceptions to be approved here 
case by case. 

> On 3 May 2023, at 18:42, Giuseppe D'Angelo via Development 
>  wrote:
> 
> Il 02/05/23 10:58, Volker Hilsheimer via Development ha scritto:
>> During the header review, but also in API discussions leading up to it, we 
>> had a few cases where it would have helped if we had clearer guidelines 
>> about when to use scoped enums, and when not.
>> Scoped enums have some clear technical advantages (such as better type 
>> safety, thanks to no implicit conversion to int). And they sometimes result 
>> in better APIs when enum values don’t have to repeat the enum’s name in 
>> order to be clear.
> 
> Should we vote on this? To me it's a no brainer: any new enumeration added to 
> Qt shall be an enum class.
> 
>> But sometimes it’s also creating too much verbosity to use a scoped enum 
>> (ie. Qt::Orientation::Horizontal would perhaps not be an improvement).
> 
> I wouldn't consider this tiny bit of extra verbosity a huge impediment. Note 
> that Qt::Horizontal is violating the API naming guidelines. It should've been 
> called Qt::HorizontalOrientation. How is that now better than 
> Qt::Orientation::Horizontal?
> 
> No, Qt::Horizontal isn't "unambiguous" so it can't be non-qualified. Does it 
> refer to what? Text alignment? Text direction? Layout direction? (Hint: none 
> of these.)
> 
> The extra verbosity e.g. in switches can be tamed; one more reason to upgrade 
> to C++20:
> 
> https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1099r5.html
> 
> 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
> 
> -- 
> Development mailing list
> Development@qt-project.org
> https://lists.qt-project.org/listinfo/development
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Thiago Macieira]

On Wednesday, 3 May 2023 09:40:42 PDT Giuseppe D'Angelo via Development wrote:
>  To me it's a no brainer: any new enumeration
> added to Qt shall be an enum class.

I'd say that any new enumeration in the Qt namespace should be enum class, but 
enums in classes may not be so if they're sufficiently descriptive already.

-- 
Thiago Macieira - thiago.macieira (AT) intel.com
  Cloud Software Architect - Intel DCAI Cloud Engineering


smime.p7s
Description: S/MIME cryptographic signature
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

Re: [Development] API style guide: scoped enum or not?

[Giuseppe D'Angelo via Development]

Il 02/05/23 10:58, Volker Hilsheimer via Development ha scritto:

During the header review, but also in API discussions leading up to it, we had 
a few cases where it would have helped if we had clearer guidelines about when 
to use scoped enums, and when not.

Scoped enums have some clear technical advantages (such as better type safety, 
thanks to no implicit conversion to int). And they sometimes result in better 
APIs when enum values don’t have to repeat the enum’s name in order to be clear.


Should we vote on this? To me it's a no brainer: any new enumeration 
added to Qt shall be an enum class.




But sometimes it’s also creating too much verbosity to use a scoped enum (ie. 
Qt::Orientation::Horizontal would perhaps not be an improvement).


I wouldn't consider this tiny bit of extra verbosity a huge impediment. 
Note that Qt::Horizontal is violating the API naming guidelines. It 
should've been called Qt::HorizontalOrientation. How is that now better 
than Qt::Orientation::Horizontal?


No, Qt::Horizontal isn't "unambiguous" so it can't be non-qualified. 
Does it refer to what? Text alignment? Text direction? Layout direction? 
(Hint: none of these.)


The extra verbosity e.g. in switches can be tamed; one more reason to 
upgrade to C++20:


https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1099r5.html

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: Firma crittografica S/MIME
-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development

[Development] API style guide: scoped enum or not?

[Volker Hilsheimer via Development]

During the header review, but also in API discussions leading up to it, we had 
a few cases where it would have helped if we had clearer guidelines about when 
to use scoped enums, and when not.

Scoped enums have some clear technical advantages (such as better type safety, 
thanks to no implicit conversion to int). And they sometimes result in better 
APIs when enum values don’t have to repeat the enum’s name in order to be clear.

But sometimes it’s also creating too much verbosity to use a scoped enum (ie. 
Qt::Orientation::Horizontal would perhaps not be an improvement).


Volker

-- 
Development mailing list
Development@qt-project.org
https://lists.qt-project.org/listinfo/development