I agree this is a very big problem that needs to be fixed. When we have a user of 4+ years stumbling across important parts of the language only now, that indicates a serious issue with the documentation.
I used to be of the opinion that the .ino files of Arduino sketches were written in C++ and so we only needed to document this fact so that people could use one of the excellent C++ references that already exist on the Internet (e.g., cplusplus.com to learn C++. This would mean the Arduino Language Reference only needed to document the standard Arduino core API (e.g., digitalWrite()), and perhaps some fundamentals of C++ to get beginners started. I think the Language Reference already does a reasonably good job of documenting the Arduino core API.
My experience when I started with Arduino as someone with very little programming experience was that I started writing sketches following the Arduino Language Reference and quickly hit this point of "That's all there is to the Arduino Language? I need more." Because of this, I was about to abandon Arduino and move on to a more capable microcontroller platform when I found some information on the Forum that made me realize that the entire C++ language was available to me. I wasn't stuck with some kiddie programming language, I was using a standard, professional programming language without even realizing it! That was when I knew Arduino was the right choice for me.
I felt that the Arduino Language Reference could do a better job of making that bridge so that people wouldn't need to stumble upon it by chance. I submitted a suggestion to make some small changes to the reference home page to make it clear that it was C++:
To my surprise, I was informed by several very knowledgeable Arduino employees that .ino files are not written in C++, they are written in Arduino Language, and it would be wrong to tell the readers that it was C++. As an Arduino employee, I am required to share their opinion that there is an Arduino Language. I do understand the reasoning behind saying that .ino files are not C++, since most sketches are indeed not valid C++ code (though it only takes adding a few simple lines of code to make them valid C++).
So now I face this very tricky dilemma. The Arduino Language Reference is the only official documentation of the Arduino Language, but it is far from complete. I think it's essential for a programming language to be completely documented.
The obvious solution is to add to the reference until the complete programming language is documented, but this is a huge task. It also will likely make the reference less friendly to beginners. Dynamic memory allocation and templates are not topics a beginner needs to know about. The upside of the solution of making the Arduino Language Reference comprehensive is that we could write the documentation in a way that is specific to the language's use on microcontrollers. One problem with the C++ references is that they contain information that doesn't apply to Arduino and so you need to read those references with a mental filter to sort out which are the useful bits.
The other idea I've been kicking around lately is to say that C++ is a subset of Arduino Language. Any valid C++ is valid Arduino Language, but not all Arduino Language is valid C++. This would allow us to stick to Arduino's official claim that they invented a new programming language, while still being able to pass off the burden of documenting the entire language on to others.
I'd be very interested in any input on how we can make this situation better.