Add constexpr to the refrence and favour them over #define

[pert]

My perspective is that it's essential to provide a gentle learning curve for beginners while also allowing users to to progress as far as they want rather than hitting some point where they grow out of Arduino. It is possible to do both. The language reference currently does a great job of the former, but a horrible job of the latter. The novice will quickly reach the point where they need more from the Arduino programming language, but there is no bridge between the beginner friendly basics of the language we already have and all the incredibly useful features of the language we don't document. The user must get lucky enough to stumble over the information that the entire C++ language is available to them on a random post buried among the millions on this forum or an obscure, non-obvious wiki page on Github. In the other thread where we discussed this, we had someone who had been using Arduino for 4 years and just happened to learn by chance that they could use templates in the Arduino programming language. I don't think that's an acceptable situation.

#include arduino.h

The file is named Arduino.h.

For beginners, searching on "Arduino" returns far more useful results than C or C++.

This discussion isn't about beginners. This is about the more advanced users. They matter too.

[westfw]

Is there a standard mechanism for setting up a .h file so that C++ gets to use constexpr, and plain C gets the closest equivalent that is still plain C?  Significant parts of Arduino SW are still written in C...

[jperryma]

My perspective is that it's essential to provide a gentle learning curve for beginners ... The language reference currently does a great job

The language reference is terrible at teaching the Arduino language. If you understand C, then it's a great way to get up to speed. To learn C, there are tutorial sites and youtube videos that are more suitable.

The novice will quickly reach the point where they need more from the Arduino programming language, ...
In the other thread where we discussed this, we had someone who had been using Arduino for 4 years and just happened to learn by chance that they could use templates in the Arduino programming language. I don't think that's an acceptable situation.

4 years and they never realized this was C++. That's sad but they were at fault.

Documenting constexpr and templates in the Arduino reference is a terrible idea. The Arduino reference is already too large for beginners. Discussing these in the Arduino forums will never do them justice. They are C++ features that are regularly discussed in the C++ forums and often very in great detail. If you truly want to extend your C++ knowledge, you will learn much more there.

Discussing the basics here is fine but people need to learn there are additional resources that can be far more useful.

This discussion isn't about beginners. This is about the more advanced users. They matter too.

I agree but they can easily learn about advanced features (e.g. templates) in the C++ forums. In fact, they will get exposure to several features that go unnoticed here. If discussed here, it becomes difficult to find important information that is unique to Arduino for those features.

The file is named Arduino.h.

Sorry, my bad. I'm accustomed to lower case header file names.

Regards, Jon.

[jperryma]

Is there a standard mechanism for setting up a .h file so that C++ gets to use constexpr, and plain C gets the closest equivalent that is still plain C?  Significant parts of Arduino SW are still written in C...

As far as I can tell, everything is compiled using C++. Is there a situation where constexpr is getting an error in the plain C code?

Regards, Jon.

[pert]

4 years and they never realized this was C++. That's sad but they were at fault.

How are they expected to learn that when it's not mentioned in the documentation?

Documenting constexpr and templates in the Arduino reference is a terrible idea. The Arduino reference is already too large for beginners. Discussing these in the Arduino forums will never do them justice. They are C++ features that are regularly discussed in the C++ forums and often very in great detail. If you truly want to extend your C++ knowledge, you will learn much more there.

If you look at my proposals, the first one is to provide a link to a place where people can learn about C++, rather than fully documenting the language in the Arduino Language Reference.

You'll also see that in my second proposal to document the entire language I say "we would need to have some way of separating the advanced topics that beginners should not be immediately exposed to from the rest".

Discussing the basics here is fine but people need to learn there are additional resources that can be far more useful.

And that's something that is not done at all in Arduino's documentation currently. You won't find any further documentation of the Arduino programming language anywhere else. So it's very easy to come to the conclusion that what is in the Arduino Language Reference is the entire language. We need to somehow provide documentation for the entirety of the language.

it becomes difficult to find important information that is unique to Arduino for those features.

Anything on the Forum is extremely difficult to find because the Forum is a huge disorganized mess. We should not count on information in the forum as documentation. This "information unique to Arduino for those features" is the benefit of my second proposal of documenting the entire language. Currently, we have no official place to document this sort of information so people must be lucky enough to stumble across it in some obscure forum thread or bug ticket.

[jperryma]

You won't find any further documentation of the Arduino programming language anywhere else.

Actually, it's at the bottom of the first page.

Looking for something else?

See the libraries page for interfacing with particular types of hardware. Try the list of community-contributed code. The Arduino language is based on C/C++. It links against AVR Libc and allows the use of any of its functions; see its user manual for details.

It tells you specifically to look at C and C++. It would be easier to recommend rewording for this section instead of asking for a large amount of documentation that must be maintained.

Anything on the Forum is extremely difficult to find because the Forum is a huge disorganized mess.

I personally like stack overflow because users rate the value of answers, supports tags, allows user changes and comments. Maybe you can talking them into moving to a better forum.

Regards, Jon.

[westfw]

As far as I can tell, everything is compiled using C++. Is there a situation where constexpr is getting an error in the plain C code?

files with the .c extension are compiled as C, rather than C++.  So, for example, if I change the definition of HIGH in Arduino.h to use constexpr, I get:

Code: [Select]

/Applications/Arduino-1.8.7.app/Contents/Java/portable/packages/arduino/tools/avr-gcc/5.4.0-atmel3.6.1-arduino2/bin/avr-gcc -c -g -Os -Wall -Wextra -std=gnu11 -ffunction-sections -fdata-sections -MMD -flto -fno-fat-lto-objects -mmcu=atmega328p -DF_CPU=16000000L -DARDUINO=10807 -DARDUINO_AVR_UNO -DARDUINO_ARCH_AVR -I/Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/cores/arduino -I/Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/variants/standard /Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/cores/arduino/wiring_pulse.c -o /tmp/ArduBuild/core/wiring_pulse.c.o
In file included from /Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/cores/arduino/wiring_private.h:31:0,
                 from /Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/cores/arduino/wiring.c:23:
/Applications/Arduino-1.8.7.app/Contents/Java/hardware/arduino/avr/cores/arduino/Arduino.h:41:11: error: expected '=', ',', ';', 'asm' or '__attribute__' before 'int'
 constexpr int HIGH = 0x1;

User code is also permitted to be C...

[pert]

Actually, it's at the bottom of the first page.

Please post a link to where you found that. I can't find it anywhere. I know the old version of the Arduino Language Reference did have some additional text like that, and there is an old version of that which is still online only by accident:
https://www.arduino.cc/en/Reference/HomePage2
but that page doesn't contain the same text you posted.

I personally like stack overflow because users rate the value of answers, supports tags, allows user changes and comments. Maybe you can talking them into moving to a better forum.

I also like Stack Exchange a lot, though the moderation of Arduino Stack Exchange is a big struggle due to most people who submit questions not bothering to take the time to understand how to use Stack Exchange. However, Stack Exchange and the Arduino Forum serve two separate purposes. This forum it works well enough for the purpose it's intended to serve. The forum is not suitable for documentation, but it was never intended to be used for that.

[jperryma]

Please post a link to where you found that. I can't find it anywhere. I know the old version of the Arduino Language Reference did have some additional text like that, and there is an old version of that which is still online only by accident:

Apparently the online reference has been reorganized but the information is still there.

STRUCTURE

The elements of Arduino (C++) code.

While this is not the best way to document this, they are certainly trying by reorganizing the reference. There's a link on the page for recommending documentation changes. Maybe that would be a good location to make recommendations. I would suggest you limit the suggestions to focus on beginners to make this acceptable.

Regards, Jon.

[pert]

Apparently the online reference has been reorganized but the information is still there.

Only still there in an obscure orphan page that will be deleted as soon as someone from the website team gets the time. In the real Arduino Language Reference, the information is certainly not still there:
https://www.arduino.cc/reference/en/

While this is not the best way to document this

The lead technical writer at Arduino has this to say about that text:
https://github.com/arduino/reference-en/issues/476#issuecomment-460056507

I will investigate why we have this "The elements of Arduino (C++) code." sentence that is not how it should be.

My understanding is that it's their intent to remove the "(C++)" from that text.

they are certainly trying by reorganizing the reference.

There was no reorganization of the reference. What happened is a few years ago Arduino created an awesome new system where the content of the Arduino Language Reference is stored in a GitHub repository as asciidoc files so that anyone can contribute to it by submitting pull requests to that repository. The Arduino Language Reference web pages are automatically generated from that content. It wasn't a reorganization, it was just a change in the way the content is published. During that change, some of the text was removed from the home page, but the structure and content of all the other pages in the Language Reference were left as they were.

I fail to understand how you can interpret the removal of the sentence "The Arduino language is based on C/C++" from the reference home page as "trying".

There's a link on the page for recommending documentation changes. Maybe that would be a good location to make recommendations.

I'm well aware of this. I'm the top contributor to the arduino/reference-en repository and the lead maintainer of the project. But I'm glad you brought it up because I would love to see more of the Arduino community take advantage of this excellent opportunity to collaborate on such important documentation. There is a tutorial here:
https://create.arduino.cc/projecthub/Arduino_Genuino/contribute-to-the-arduino-reference-af7c37

I would suggest you limit the suggestions to focus on beginners to make this acceptable.

This is the sole documentation of the Arduino programming language. It needs to provide for the needs of all users, not only beginners. Making things beginner friendly is essential, but the goal is to help people eventually progress beyond the beginner stage. Too often in technical subjects I see these knowledge gaps that can be such a huge barrier. I think the attitude people have is "someone will tell you about that". That someone would traditionally be a professor, mentor, or coworker. But the people who are teaching themselves these subjects often don't have access to the gatekeepers who judge whether they're worthy of receiving the secret knowledge that allows them to move to the next level. Maybe they'll be able to sort through mountains of garbage on Google until they find that information buried in some random comment thread, maybe they won't. The only purpose of a system like that is to prevent anyone outside the inner circle of universities and industry from gaining proficiency. Arduino is about freeing the knowledge to make this stuff accessible to everyone. That means providing proper documentation.

[Juraj]

you could argue the C is not a language, but a simplification of assembly. you can still use assembly in C. and C++ builds on C. you can use C and assembly in C++. the reference of C doesn't contain reference of assembly

[pert]

you could argue the C is not a language, but a simplification of assembly.

You could argue that, but everyone would laugh at you because it's clearly wrong.

you can still use assembly in C

I really don't consider inline assembly in C to be a valid analogy for the situation with Arduino programming language and C++. C and C++ is much closer. You can consider C to be a subset of C++, just as you can consider C++ to be a subset of Arduino programming language.

the reference of C doesn't contain reference of assembly

It will contain documentation of asm(). But as I said already, I reject that analogy. Lets move on to your better analogy of C++ and C, which you conveniently didn't mention in this statement. Any good C++ reference will document the parts of C++ that are shared with C.

[Juraj]

You could argue that, but everyone would laugh at you because it's clearly wrong.
I really don't consider inline assembly in C to be a valid analogy for the situation with Arduino programming language and C++. C and C++ is much closer. You can consider C to be a subset of C++, just as you can consider C++ to be a subset of Arduino programming language.
It will contain documentation of asm(). But as I said already, I reject that analogy. Lets move on to your better analogy of C++ and C, which you conveniently didn't mention in this statement. Any good C++ reference will document the parts of C++ that are shared with C.

gcc first generates assembly and then compiles it to machine code

[westfw]

The "assembly" produced or includable in C is not standardized, and is thus not a "subset" of C in any way.
(whereas C is a standardized subset of C++ (except for divergence), and C++ is a standardized subset of Arduino (if you consider Arduino a separate lanaguage.))

Not all C compilers generate asm on the way to machine code, BTW.  I've used at least one where they'd skip that step unless it was "necessitate" by, say, using inline asm in the C code.  Which resulted in some very mysterious bugs when the assembler didn't support the same data types as the compiler :-)