The Arduino programming language is not fully documented

[per1234]

The Arduino Language Reference is the only official documentation of the Arduino programming language, but it is far from complete.

Some examples of important things that are not mentioned in the the Arduino Language Reference:

• C string functions
• Default arguments
• Overloaded functions
• enum
• Templates
• Classes

How can users be expected to learn these parts of the Arduino programming language from the current documentation?

In my own learning journey with Arduino I started writing sketches using the Arduino Language Reference as a guide and quickly reached a point where I said to myself "Is that all there is to the Arduino programming language? I need more." I was about to give up on Arduino and move on to a more capable microcontroller platform when I stumbled across a post on the Arduino Forum that made me realize that there was so much more to the Arduino programming language, but I would need to use a C++ programming reference to discover it.

Once I realized this, I knew Arduino was the right choice. So it worked out OK for me, but this is far from an ideal learning path. How many other users in my situation would never chance upon that forum post? I know I'm not the only one who has had this sort of experience because it comes up regularly on the forum.

---

I can see two possible solutions:

Document the differences between the Arduino programming language and C++

Create a new page on arduino.cc that explains what the Arduino programming language is:

• A brief history (Processing, Wiring).
• A description of the sketch preprocessing processes that make the Arduino programming language different from C++:
  • Concatenate .ino files, starting with the file that matches the folder, followed by the rest in alphabetical order. Save the resulting file with a .cpp file extension.
  • Add #include <Arduino.h> if not already present.
  • Add function prototypes for any functions that don't already have one.
• A link to an external C++ language reference (e.g., http://www.cplusplus.com, https://en.cppreference.com)
• Add a link to the new page from the description at the top of the Arduino Language Reference home page.

This means the Arduino Language Reference only needs to document the Arduino core API and some basics to get beginners started, which it already does a good job of.

Advantages:

• Easy to implement and maintain. Others are responsible for the huge task of completely documenting the language.
• Makes it easy for the user to understand how to apply their Arduino programming language knowledge to writing C++ as well (e.g., writing Arduino libraries).

Disadvantages:

• The external C++ reference will contain information that is not applicable to Arduino. The reader will need to have some intuitive filter for which parts of that documentation are useful and which can be ignored.

Fully document the Arduino programming Language in the Arduino Language Reference

Advantages:

• We can custom tailor the documentation for Arduino.
• We may be able to write the documentation so that it is easier to understand for the target audience than the external C++ documentation.

Disadvantages:

• A huge amount of work to implement and maintain.
• Has the potential to make the Arduino Language Reference less friendly to beginners. I think we would need to have some way of separating the advanced topics that beginners should not be immediately exposed to from the rest.

Related

• Document ternary operator #519 / Created Ternary operator file under Control Structure #684
• Add log() and other avr-libc math functions to reference #522
• constexpr should be mentioned and discussed on the const page #709
• Compound bitshift description #725
• Add lambdaExpression.adoc #778
• Document hash prefixed functions other than #define/#include #794
• ISR routine documentation #799
• Round() is mentioned in the Float ref page but neither have a ref page, nor is listed in the top Language Ref page #989
• Warning about clearing of uninitialized global variables on reset Arduino#11682
• https://forum.arduino.cc/t/no-documentation-on-ternary-operators-on-language-ref-page-et-al/87004/8
• https://forum.arduino.cc/t/does-the-bracket-matter/599746/4
• https://forum.arduino.cc/t/how-to-turn-an-integer-into-a-string/612305/3
• https://forum.arduino.cc/t/language-question/633964
• https://forum.arduino.cc/t/c-types/672762
• https://forum.arduino.cc/t/unusual-language-construct/697008
• https://forum.arduino.cc/t/difficulties-with-included-c-files/698153
• https://forum.arduino.cc/t/undefined-reference-to-tone-after-including-arduino-h/698830
• https://forum.arduino.cc/t/meaning-of-void-doesnt-return-a-value/960173/35
• https://forum.arduino.cc/t/documentation-on-additional-functions/1030122
• https://forum.arduino.cc/t/complete-reference-for-arduino-programming-language/1112176
• https://forum.arduino.cc/t/decent-documentation/1299627

[animeshsrivastava24]

@per1234 Please can you guide on how to proceed to work on this issue. I want to work to resolve this issue by providing relevant documentation.
Also, can you guide me on how to work on "Arduino Core Documentation", I want to work on it both voluntarily and as a way to make my Season of Docs application stronger.

[per1234]

Please can you guide on how to proceed to work on this issue. I want to work to resolve this issue by providing relevant documentation.

Thanks for your offer to help! My goal for this issue was to start a discussion on how to resolve this. Hopefully some folks from Arduino will participate because this is a big decision.

Until we have decided on how to proceed, no documentation work for this issue can be done. If we were to chose my second proposed solution, it would create a lot of documentation work on which help from the community would be very welcome.

can you guide me on how to work on "Arduino Core Documentation", I want to work on it both voluntarily and as a way to make my Season of Docs application stronger.

Since this will be new documentation, I think some internal discussion at Arduino will be required before we create the page where it will be published. That likely would only happen after a Season of Docs application for the Arduino Core Documentation project was selected. However, you are welcome to write some documentation and publish it to your own GitHub repository, blog, Arduino Project Hub project, etc. There is a tremendous amount of excellent Arduino documentation available online from 3rd parties who wrote and published it on their own initiative without any interaction with the Arduino organization.

[animeshsrivastava24]

@per1234 I have created a repository for the Arduino Core Documentation.

https://github.com/animeshsrivastava24/Arduino-Core-Documentation/blob/master/README.md

https://github.com/animeshsrivastava24/Arduino-Core-Documentation/wiki/1.-Introduction-to-Arduino-Core

Please, help me with feedback and suggestion.

[matthijskooijman]

I would be very much in favor of the first solution. One additional advantage is that making users aware of the relation to C++ would also open up a lot of extra resources (documentation, tutorials, stackoverflow posts, etc.) to them, which they previously did not realize applied to Arduino (this is different from the advantage you already listed, which is about applying Arduino docs and experience to C++ projects).

In addition to the things you already listed, I think we should make explicit that:

• Exceptions are disabled in Arduino (at least on AVR, but I think we do this on all platforms?).
• The C++ library (libstdc++) and STL is not available on all platforms (in particular not on AVR, not sure about all others).
• The C++ version might vary per platform.

[theHacker]

Hi, Arduino newbie here. I just stumped upon this issue. I read the language reference and was puzzled by "How are libraries able to use additional language features like class and I am not?", until I tried out using the same syntax and it just worked.

Since this issue has been open for several years, might I suggest a pragmatic approach to improve the situation without committing to any direction:
Just add an info box to the language reference page, sth like

Please note:
This reference is not fully complete. There are more language features similar to C++.
A list of missing features can be found {link to this PR}.

This will point anybody who wants more information in the right direction.

[MacDada]

language features similar to C++

They are not similar - they are the same. Arduino "language" is not a separate language -> it IS C++.

The difference is not in the language itself, it is the fact that not all stuff from C++ standard library is available + there is extra (pre)pre-processing done on top of standard C++ build stuff. It is just GCC under the hood. GCC does not claim that it compiles some separate "arduino language" xd