Documentation should use more specific types

[matthijskooijman]

Currently, the documention uses types like "unsigned long" (for example here: https://www.arduino.cc/en/Reference/millis). However, this is only correct for the AVR architecture, on e.g. the Due a long is (AFAIK) 64 bit, but the code explicity uses uint32_t. It would make sense to adopt the same explicit approach in the documentation (and, while we're at it, probably apply this to the code of the AVR port as well).

[agdl]

@matthijskooijman +1 I think that actually all the documentation and software should use standard data types like uint8_t, int32_t etc. In this way it is immediately clear the "dimension" of a variable and code can be optimized and standardized

[agdl]

BTW once upon a time someone from the high levels told me that for beginners standard data types are not too friendly...

[matthijskooijman]

BTW once upon a time someone from the high levels told me that for beginners standard data types are not too friendly...

They might be a bit scary-looking, that's true, but the using platform-dependent types of unknown size looks nicer but doesn't work as well. We could consider introducing more friendly alternative names, but then Arduino code becomes even less portable, and things people learn will also be less reusable.

Perhaps a decent alternative is to use the standard names in the docs, but make them a link to a page explaining what these types mean? Anyone that is confused about a typename can click it and get an explanation?

[agdl]

I think we need @tigoe

[tigoe]

I would rather we adopt the Arduino types to new platforms as we go. As you said, Arturo, the point in making them in the first place was to make the language more readable for a non-technical audience. I'd like to maintain that approach as we move to new platforms.

[matthijskooijman]

@tigoe, what "Arduino types" do you mean exactly? There is the custom "byte" type, but AFAIK no other custom integer types are defined. The AVR core and documentation use int and long for the bigger integers, but those can't be portably used on other platforms, since their sizes will be different.

Or is your suggestion to introduce new types (e.g. word and dword in addition to byte or something)?

[tigoe]

I mean the ones listed here, as used in Arduino sketches over the last ten years:
https://www.arduino.cc/en/Reference/HomePage

I'm suggesting that if they don't exist for other platforms, we introduce them, to make those platforms compatible with Arduino as it currently exists.

[matthijskooijman]

@tigoe, Oh good point. Seems I totally missed the short and word types (though "word" is a bit of an ambiguous term in general - I think it originally referred to a machine's word size, for x86 it was used to refer to 16-bit, with double-word being 64-bit, arduino seems to use it for 16-bit on AVR and 32-bit on Due, which doesn't actually make it very useful here). On additional complication with these types is that currently short is signed and word is unsigned, and I don't think C supports just adding "signed" or "unsigned" to a custom type to change its signedness.

So, regarding types, it seems we don't have any Arduino-specific / user-friendly set of types that is complete (e.g. has signed and unsigned integers of 8, 16, 32 and possibly 64 bits wide) and portable. So that leaves us with two options for making this consistent:

• Use the existing, standard types like uint32_t.
• Introduce new types to make the existing types complete.

I'm not so sure what the best option is here. Using standard types makes code, as well as learned concepts, more portable. These types also clearly and unambiguously indicate the signedness and size of the type, at least once you've learned how they work. I'm inclined to stick with the standard types, also because it is probably hard to define a new set of typenames that are clear and unambiguous enough. "byte" is well-defined, "short" is less obvious and "word" is both unobvious as well as ambiguous.

For lack of any well-defined names for specific bit widths, using the number of bits in the type (like the standard types) might be useful. To make the names less cryptic, they could be more verbose, an drop the not-so-useful _t postfix. E.g. types like signed_16bit_int or unsigned_8bit_int could work, though I'm afraid they're so long and verbose nobody will want to type them...

[tigoe]

I'd be more inclined to introduce new typws to make the existing types complete. I have always found the _t extension irritating, and uint8, uint16, uint32, etc, too terse, and too easy to mis-type as unit (not to mention how auto-correct does the same to them).

As for being so long and verbose, nobody wanting to type them: that hasn't been my experience, outside of people who've been classically trained in C programming. Tersness is a weakness, in my opinion. It's one of the things I'm trying to fight against, to get people to use natural language more in code, so it's readable to people from many backgrounds. If we really want programming to be a common literacy, then the grammar of it has to be articulate.

[Breidenbach]

Oooh - back to COBOL! :-)

On Feb 5, 2016, at 8:49 AM, tigoe notifications@github.com wrote:

I'd be more inclined to introduce new typws to make the existing types complete. I have always found the _t extension irritating, and uint8, uint16, uint32, etc, too terse, and too easy to mis-type as unit (not to mention how auto-correct does the same to them).

As for being so long and verbose, nobody wanting to type them: that hasn't been my experience, outside of people who've been classically trained in C programming. Tersness is a weakness, in my opinion. It's one of the things I'm trying to fight against, to get people to use natural language more in code, so it's readable to people from many backgrounds. If we really want programming to be a common literacy, then the grammar of it has to be articulate.

—
Reply to this email directly or view it on GitHub #4525 (comment).

[cousteaulecommandant]

I agree that the [u]intX_t types are a bit cryptic and unnecessarily scary. I have seen implementations that use custom types such as u8 or s32 for unsigned/signed types; maybe that's excessively short though. As for verbosity, what about unsigned8 or signed_32b? (not sure if it looks better with or without the underscore, and with or without the b; I think without either)

As for the documentation, I'd just say "a 32-bit signed integer" when necessary.

re: the original comment, I'm not sure a long is 64 bits in ARM; according to http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.dui0472l/chr1359125009502.html it is 32 bits just like int (the only platform I've heard about that uses 64 bit longs is x86_64/amd64).

[tigoe]

I think @damellis should weigh in on this, as he's more informed than I when it comes to the choices for data type names originally.

[q2dg]

Well...six months ago...#3801

[shiftleftplusone]

about cousteaulecommandant's and tigoe's statements:

the C standard data types listed in < stdint.h > are
int8_t, int16_t, int32_t, int_64_t, uint8_t, uint16_t, uint32_t, uint64_t, (...),
and Arduino should apply to the standards!!
why establish a non-standard-C-compliant datatype just for Arduino?
C is C is C, and either C user who is learning C for Arduino should learn to use the correct rules for standard C from the start - or one day he will fail terrificly in "real world" environments (e.g., gpp on Raspberry Pi) !!

[cousteaulecommandant]

@shiftleftplusone
Well, first of all Arduino is based in C++ and not C. Afaik the [u]intN_t types exist in C++ too, but I wanted to clarify this.
Second, defining new types is not "non-standard-C[++]-compliant"; nowhere in the standards does it say that you can't define your own types. It's just non-standard, not non-standard-compilant.
Third, I think the reason standard types are not often used in Arduino is the fact that the Arduino spirit is to be newbie-friendly: byte is used instead of unsigned char, because everybody understands what a byte is but the concept of a "character without a sign" is weird; word instead of unsigned int because it kinda looks prettier, and boolean instead of bool because, uh... well, honestly I don't get it either. What we were discussing was whether a type like uint32_t is consistent with the rest of Arduino types and functions.

From what I have seen, Arduino is not intended as a tool to teach C or C++ and their standard libraries but rather to teach programming in general and to be "easy to use". For example, it introduces setup() and loop() instead of just using the standard main(); also it uses a lot of macros and functions and names for simple things that would be a one-liner in C++ but would look a bit ugly and would require some "advanced" (not really) knowledge of "C/C++". In general, it tries to hide the "ugly details" from the user, such as how to handle AVR's registers, how to use the timers, things such as the fact that signed overflow in actual C and C++ causes "undefined behavior" (which btw also does in Arduino but the docs say it doesn't)...

For really learning C and how to use microcontrollers, the Arduino IDE is probably not the best choice.

PS: sorry for wall of text. I really need to learn to summarize.

[shiftleftplusone]

Objection!
Arduino IS helpful for learning C-programming, as it uses a gpp C(++) compiler and C/C++ syntax, and actually it's the more helpful for learning the more it will comply to standards!
So it should be C compliant to C standards - as much as possible - and not always cook it's own soups especially where there is absolutely no need for, e.g. for standard C(++) data types, period.

[tigoe]

@cousteaulecommandant pretty much sums up our philosophy in a nutshell. I don't think ANSI C is such a perfect standard that it must be adhered to at the expense of legibility. People can learn the standards after they've learned the more basic concepts, and so far, Arduino's proven pretty good for teaching those basic concepts, in part because it doesn't adhere to the standards. If you want to use the standards in your own examples, go ahead. They'll compile just fine.

[techpaul]

Once you have trained someone with bad habits it takes longer to unlearn the bad habits, even with someone leaning over you watching every key press.

I am regularly involved with learners fro age 14 to 30, bad habits and wrong ways stick until they waste a day tracking down an issue which was their bad habit, no matter how many times you tell them, show them, smack them around the head they keep on.

Don't even get me on exam boards and bad habits.....

[q2dg]

I don't mind if Arduino types definition must follow a standard or not...but please: give it some consistency. As I said in #3801:

*"word" type is a 2-byte data type only in AVR boards but in Due (and Zero??) it is a 4-byte data type. Not very logical.

*"char" type in a signed type in AVR boards but in Due (and Zero??) is unsigned. OMG!!

*I repeat here: maybe should be added a table somewhere in web simply showing three columns for each data type (row): the bytes stored in both architectures (AVR & ARM) if it's signed or not and their resepective numerical boundaries. This would help to see, for instance, that in Due (and Zero??) the "word" type and the "unsigned long" type are the same and also the "int" type and the "long" type, whereas in AVR the "short" type is equal to "int" type. What a mess.

Thanks

[shiftleftplusone]

apart from logic or not it is a matter of libs design if there will happen a lot of mess or not.
It's quite common that int, word, long are ambiguous and vary depending on the platform type and the processor address bus width (sorry, correct English idiom?).

But e.g., if a AVR lib is designed to handle char as signed then bullshit can be reliably expected to happen if the same code will be compiled to unsigned char when targeting an ARM.
Or if the size of a a parameter is essential for functions handling with sizeof(datatype).
Or when dereferencing a pointer to an int value.

So for variable definitions (at user interface level) working on either platforms unambiguous datatype dimensions are essential, i.e. the C11 stdint datatypes. Simply re-define in all existing libs former int as int16_t or former long as int32_t, and everything will be fine.

Ok, perhaps not everything , but most of it. (char for Serial class is another issue... )

[techpaul]

char/unsigned char for nearly any 8 bit interface, LCD, SPI, I2C/TWI.....

The main issue is the Arduino documentation does not say like C/C++ that these types may vary across platforms, FOR EXAMPLE it states on https://www.arduino.cc/en/Reference/Char

"The char datatype is a signed type, meaning that it encodes numbers from -128 to 127. For an unsigned, one-byte (8 bit) data type, use the byte data type. "

No platform dependency it states it is ALWAYS this when it is not

[shiftleftplusone]

I don't see your point - who is missing something? (or are you just confirming what I already wrote?)
actually char IS platform dependent, as already statet (char is unsigned for ARM cpus like the DUE), and so it's ambigous!
So only
int8_t
and
uint8_t
are well-defined and un-ambiguous and should supersede the vintage data type names.

[techpaul]

You and I know that char is platform dependent new users and many others do NOT so

either - Leave the current DOCUMENTATION mess

or - Change compiler settings to match documentation for ALL platforms

or - Change documentation to say exactly what each type is for EACH platform

or - Change types to a standard set that are EXPLAINED to new users and DOCUMENTED

Current documentation mess is STILL AVR specific, and most neweer platforms are ARM, so many gotchas for new users and new hobbyists let alone students.

[shiftleftplusone]

ok, thank you for clarification, your point was not clear to me.
I fully agree.
Nevertheless:
compiler settings are not supposed to be able to be changed - the gnu compiler for AVR works different from the ARM compiler, also for ARM on Raspi boards it's like ARM on Arduino.
So it's a matter of ducumentation and standardization to C11 stdint standards.

[cousteaulecommandant]

maybe should be added a table somewhere in web simply showing three columns for each data type

Yes please, let's do this.

it states on https://www.arduino.cc/en/Reference/Char: "The char datatype is a signed type..."

Bug. Either a "documentation bug" or an Arduino bug, you choose. Either fix the documentation or use -fsigned-char (or -funsigned-char and make char always unsigned). Although I prefer things to be homogeneous I don't think overriding the ARM standard ABI specification is a good idea. (Also if we do this we could go further and force int to be 16 bits on ARM, but I don't think this is possible in GCC.)

(1) either - Leave the current DOCUMENTATION mess
(2) or - Change compiler settings to match documentation for ALL platforms
(3) or - Change documentation to say exactly what each type is for EACH platform
(4) or - Change types to a standard set that are EXPLAINED to new users and DOCUMENTED

(1) definitely no, yuck.
(2) doesn't seem possible. You can change the signedness of char (and violate the ABI standard), but it doesn't seem that you can change the size of int. It might be an interesting possibility though.
(3) Sounds boring and confusing but it might be the best option.
(4) I don't think this is necessary if functions are consistent in the usage of types. byte for unsigned char, char when actual characters are involved, short and long when the length matters (with unsigned when needed), and int when it doesn't. I'd get rid of word since it doesn't provide anything but confusion, but I'd keep byte. I'd discourage using char for anything other than characters (there's byte for that, and if you NEED negatives you should use signed char anyway).
As a last resort, I guess [u]intX_t could be used, but only if REALLY necessary. I don't think this will ever be the case since byte / short / long / long long already have the required lengths (afaik long is 32 bits in ARM as well).

[techpaul]

cousteau wrote:

maybe should be added a table somewhere in web simply showing three
columns for each data type

Yes please, let's do this.

Agreed
...

(1) either - Leave the current DOCUMENTATION mess
(2) or - Change compiler settings to match documentation for ALL
platforms
(3) or - Change documentation to say exactly what each type is for
EACH platform
(4) or - Change types to a standard set that are EXPLAINED to new
users and DOCUMENTED

(1) definitely no, yuck.

Hence various people's comments

(2) doesn't seem possible. You can change the signedness of char (and
violate the ABI standard), but it doesn't seem that you can change the
size of int. It might be an interesting possibility though.

Might do, but the compiler for each has been set to a standard for norms and
limits, to get where we are for various reasons. In some cases like char
they may well have chosen unsigned as default for a very simple reason, the
majority of char uses for ARM is as a RAW data byte. When transferring bytes
via Serial, SPI, I2C/TWI, SD Card, USB, even when we talk to LCD, it is RAW
data, any meaning depends on translation at both ends and in quite a few
cases the individual bytes are codes not numbers so need to be unsigned.

(3) Sounds boring and confusing but it might be the best option.

But is the table method you agreed with up top, if you make a table you must
refer to it from all the other places. It is what each ABI and compiler
setup has to do for each platform.

(4) I don't think this is necessary if functions are consistent in the
usage of types. |byte| for unsigned char, |char| when actual characters
are involved, |short| and |long| when the length matters (with

Remembering that char is SIGNED on AVR .. Strings should never really be
considered signed especially if you have to support UTF-8, strings are codes
not numbers.

|unsigned| when needed), and |int| when it doesn't. I'd get rid of
|word| since it doesn't provide anything but confusion, but I'd keep
|byte|. I'd discourage using |char| for anything other than /characters/
(there's |byte| for that, and if you NEED negatives you should use
|signed char| anyway).

char is signed on AVR not on ARM there is the nub of the problem.

As a last resort, I guess |[u]intX_t| could be used, but only if REALLY
necessary. I don't think this will ever be the case since |byte / short
/ long / long long| already have the required lengths (afaik |long| is
32 bits in ARM as well).

If you create a cross platform library you need to be sure what you are
doing is defined as will work on all platforms LiquidCrystal, Servo and
others are like that. Basically in those cases you need to use [u]intX_t to
be sure.

[cousteaulecommandant]

If you create a cross platform library you need to be sure what you are doing is defined as will work on all platforms LiquidCrystal, Servo and others are like that. Basically in those cases you need to use [u]intX_t to be sure.

Sure, internally I'd use those types, but externally (function parameter and return types) I'd prefer to go with "normal" types as the thing the end user will have to deal with.

BTW, I wasn't thinking of Unicode nor UTF-8 for characters, just of "smallest unit of 'text' in a string" (you can't do UTF-8 based indexing or accessing on strings anyway). Maybe the right words would have been "piece of a string", to emphasize that I don't refer to raw data in general but to a specific usage (elements of text strings).
(Also UTF-8 strings could be considered signed, and you could say that "positive chars are ASCII and negative chars are part of UTF-8 multibyte sequences"; in any case UTF-8 chars don't directly represent Unicode code points numerically.)

[matthijskooijman]

I don't think this will ever be the case since byte / short / long / long long already have the required lengths (afaik long is 32 bits in ARM as well).

The length of short, long and long long are implementation-defined, though I believe that on our current two architectures, AVR and ARM, they are the same size. I'm not sure if that's good enough to rely on though, since there might be other architectures in the future, and there are already third-party architectures right now.

[cousteaulecommandant]

Indeed, for example long is 64 bits on amd64. However in ARM it's 32 bits. While I don't think that Arduino will ever use the amd64 architecture, maybe AArch64 (64-bit ARM) is a possibility. I wasn't able to figure out how long is a long there; apparently there are multiple possible ABIs so long could be either 32 or 64 bits.
If Arduino ever moves to said architecture or another one where long is 64 bits, then what I said in my earlier comment loses its validity.

(And it will be even funnier if it moves to weirder architectures that don't have 8-bit bytes, such as some TI microcontrollers, and therefore no uint8_t type. I imagine these microcontrollers are out of the scope of Arduino though.)

[oqibidipo]

where is millis() for 101 declared? I only see avr/ and sam/ which declare it as unsigned long and uint32_t respectively; I didn't find any arc/ directory in this github.

https://github.com/01org/corelibs-arduino101
https://github.com/01org/corelibs-arduino101/blob/master/cores/arduino/wiring.c#L58

[cousteaulecommandant]

OK, so it's not part of the arduino/Arduino repository... is it some sort of fork of the Arduino IDE, or is this going to be in the main arduino/Arduino repository in a future?

In any case, if this .c is considered as part of "the standard Arduino family" covered by the documentation, then some action should be taken. Either define a Time type and make it architecture-dependent, or document deeply the type returned by millis()/micros() on different architectures, or undo arduino/ArduinoCore-arc32@3334207 (which changes uint32_t to uint64_t), or make separate 32 and 64 bit versions of millis() and micros() to ensure compatibility. The last 2 options are out of the scope of this repository.

In any case, this kinda shows either that having the same type with different sizes for different platforms is a good idea (a good C or C++ program shouldn't rely on special types having a specific size anyway, but use macros to determine it; that's why int behaves the way it does), or that this problem is more than a mere documentation issue but an implementation one.

By the way,

Since C11 stdint these explicite data types are an international standard

actually since C99, but they weren't adopted by C++ until C++11 so they're "relatively modern" there (and they are only mandatory for implementations that support those types or equivalent, which is almost always the case).

[q2dg]

So...then?

[cmaglie]

Let me recap a bit... (I'll send one post for each problem for clarity)

About millis() return type

The documentation says that millis returns an unsigend long, but:

• on sam millis returns an uint32_t (well there is no functional problem here since on sam unsigned long actually is an uint32_t)
• on 101 millis returns an uint64_t (in this case the returned type is bigger than unsigned long, btw if the user use usigned long as documented there should be no problems since the high part is truncated)

To fix this I think that the sam and 101 cores should be changed to use unsigned long. I'll prepare a PR for that.

[cmaglie]

About using fixed datatypes for every API of Arduino

Someone asked to change the Arduino API to use only fixed-size types, like int16_t or uint32_t, instead of int, long, etc...

I don't think this a good idea unless there is a real need for the type to be fixed size. Standard types in C are defined with a minimum size, that is exactly what we need for the Arduino API.

For example, look at the read() method of the Stream class:

virtual int read() = 0

the read function is defined to return a byte from the read buffer or -1 if the read buffer is empty. Question: which fixed-size type will fit here instead of int? for AVR is surely int16_t, but this type is not a good choice for ARM, where the best type is int32_t (because ARM MCUs are designed to better handle memory transfers of 32-bits). On the other hand using int32_t would fit for ARM but it will be extremely overkill on AVR (it will bring in code for signed-32-bit operations that is very expensive).

In this case the proper choice is int because what we really care is that the return value is at least 16 bit wide so it can carry a single byte or the constant -1, but it can freely scale up to 32 bits or more if this is needed to optimize, it's not a problem for the API

http://www.cplusplus.com/doc/tutorial/variables/
http://en.cppreference.com/w/cpp/language/types
https://stackoverflow.com/a/589684/1655275

int: [...] a basic integer type [...] it's guaranteed to have a width of at least 16 bits.

So, IMHO, the solution here is to keep the API as-is unless there is a real need for fixed-size types.

[cmaglie]

About fixing docs for word, char and other datatypes

quoting @q2dg:

word type is a 2-byte data type only in AVR boards but in Due (and Zero??) it is a 4-byte data type, char type in a signed type in AVR boards but in Due (and Zero??) is unsigned.

We can't change the typedef of word to a fixed-size type because this will break a lot of existing sketches and create a big backward-compatibility issue. We must live with that, like it or not.
What we can do is fix the documentation saying that word is an unsigned integer of at least 16-bit.

Same for char, adding the compiler flag -funsigned-char doesn't look like an option to me.
In the documentation we can say that char is a type of at least 8-bit (yes, the standard specifies only the minimum size...) and suggest to use it mainly to store characters (without saying anything about signedness, or maybe just saying that signedness is different on each platform and the char type may be signed or not).

[matthijskooijman]

or AVR is surely int16_t, but this type is not a good choice for ARM, where the best type is int32_t (because ARM MCUs are designed to better handle memory transfers of 32-bits)

In general, using "int" as the "fastest" type seems nice, except that this does not really apply for AVR. There, 8-bit is faster than 16-bit, but int is 16-bit anyway...

If we want to go for the "fastest type with at least x bits", we could be using the int_fast16_t type from http://en.cppreference.com/w/c/types/integer. On AVR, the uint_fast8_t actually is 8 bits wide, while I suspect it is 32-bits on ARM (haven't checked). Using these types might be a bit more complex for novice users, though.

Agreed on all other points. As for the word and byte types, we should probably discourage people from using them (e.g. mark as deprecated in the docs and remove them from examples).

[cmaglie]

In general, using "int" as the "fastest" type seems nice, except that this does not really apply for AVR. There, 8-bit is faster than 16-bit, but int is 16-bit anyway...

It's not the fastest type in general, but the fastest to handle at least 16 bits, that's what counts here.
In the example above we need 16 bit, because we need to distinguish 0xFF as byte read from the stream from -1 that means "no data available". This is only possible using a signed type that has >=16 bits.

[cousteaulecommandant]

As for the word and byte types, we should probably discourage people from using them

Personally I like byte though; I think it's a useful type with an intuitive name, whereas unsigned char is long and potentially confusing for some users (why would you use a "character" to store an integer or a bunch of bytes?). The documentation could explain that it's just defined as unsigned char though (or have a side note in the char docs for what are signed/unsigned char and how the latter is the same as byte).
(Not word though; word is useless and confusing.)

[matthijskooijman]

Good point. byte is indeed nice, though less portable.

[bperrybap]

As for the word and byte types, we should probably discourage people from using them (e.g. mark as deprecated in the docs and remove them from examples).

I tend to agree (at least for word - which is not an obvious width). While I did use custom local types like that back through the 80's and 90's to gain some local portability. This was done because there was nothing portable that was standardized back then.
The ANSI committee finally caved and created the stdint types back in 1999. My preference would be to see Arduino start encourage the use of standardized types vs creating their own - after-all it has been nearly 20 years since these standardized types were created and they are portable across platforms.

i.e. if size/width of the data matters, use stdint types.
The stdint types and names are pretty short/simple and obvious.
Perhaps it would be useful to include them in the documentation.

[datenheim]

Somehow the floting point numbers may be affected too, docs not clear enough on all occasions:

https://www.arduino.cc/reference/en/language/variables/data-types/double/

Double is not only on the Due 64 bits long but on all 32bit cores and also 64bit cores.

While I do not want to revive the discussion for the integer types arduino should be prepared to swap over to 64bit cores ... IMHO.

[cousteaulecommandant]

It should probably be changed to "DUE and other SAM/SAMD based boards" as for int. Same for unsigned int. I guess this is because the DUE was the only official ARM-based board when the documentation was written.

I still think a table would be easier to read, and maybe combine the documentation for int/short int/long int (and maybe also signed char) into a single article (same for the unsigned counterparts).

[datenheim]

"DUE and other SAM/SAMD based boards"

or maybe

"On boards with 32-Bit processors (such as Arduino Due, SAM(D), ESP...) doubles have 8-byte (64 bit) precision".

For me the fact that AVR does not have a "real" double is an implementation error and should be fat and red and blinking ;-)

IMO arduino (IDE) does not only focus on the original arduino boards - the major strength is availability of so many different platform which are quite popular under arduino-fans.

A table that is referenced on all adequate pages (also covering the floating point types!) might be a solution.

Maybe also at least one motivating sentence recommending usage of un-ambigous types is not too disturbing to beginners.

What is the list of cores based on popularity?
AVR/Cortex/SAM(D)/ESP/STM/LPC? 5-6 families aren't too much, are they?

For the ESP families the data have been stated here:
espressif/arduino-esp32#1745 (comment)
https://www.arduinoforum.de/arduino-Thread-L%C3%A4nge-der-Datentypen-beim-ESP8266?pid=45102#pid45102

[cousteaulecommandant]

or maybe

"On boards with 32-Bit processors (such as Arduino Due, SAM(D), ESP...) doubles have 8-byte (64 bit) precision".

IMO arduino (IDE) does not only focus on the original arduino boards - the major strength is availability of so many different platform which are quite popular under arduino-fans.

That implies stating that every possible architecture, officially supported or not, current or future, that is labeled as "32-bit" defines doubles as 64-bit in its ABI, which I'm not sure can be done. I'd limit the statement to all the officially supported cores, maybe suggesting that this probably applies to other 32- and 64-bit architectures as well.

For me the warning that AVR does not have no double is an implementation error and should be fat and red and blinking ;-)

Yeah, is this even allowed by the C++ standard? At least in C it goes below the minimum required precision for a double.

[datenheim]

That implies stating that every possible architecture, officially supported or not, current or future, that is labeled as "32-bit" defines doubles as 64-bit in its ABI, which I'm not sure can be done. I'd limit the statement to all the officially supported cores, maybe suggesting that this probably applies to other 32- and 64-bit architectures as well.

You are right. That is a good solution.

For me the fact that AVR does not have a "real" double is an implementation error and should be fat and red and blinking ;-)

Yeah, is this even allowed by the C++ standard? At least in C it goes below the minimum required precision for a double.

At least there could be a warning at compile time :)