Emit a warning if a prototype is not generated due to known limitations

Describe the request

Print a warning when necessary prototype generation for a function was intentionally skipped.

🙂 The user will have useful information about the cause of what would otherwise be a very mysterious compilation error.

Describe the current behavior

In order to make it easier for beginners to get started with writing Arduino sketches, and for the convenience of all users, Arduino CLI automatically generates and adds prototypes for functions defined in a .ino file of a sketch unless the sketch already contains that prototype.

Due to not needing to write them, and due to them not being mentioned anywhere in the official documentation of the Arduino Language, the average Arduino user does not know about function prototypes and takes forward declaration of their functions for granted.

In some cases, it might not be feasible for Arduino CLI to generate a prototype. For example, prototypes are intentionally not generated in the following cases:

Default parameter values

Prototypes are not generated for functions with default parameter values (https://github.com/arduino/Arduino/issues/386):

https://github.com/arduino/arduino-cli/blob/f23975438ca8ad6463fadf61e181c0bc03a20ae1/legacy/builder/prototypes_adder.go#L86-L88

Compiling a sketch with a function using default parameter values that was referenced before declaration like this:

void setup() {
  foo();
}
void loop() {}
void foo(int bar = 42) {
  (void)bar;  // fix "unused parameter" warning
}

will fail:

C:\Users\per\Documents\Arduino\sketch_oct24a\sketch_oct24a.ino: In function 'void setup()':
C:\Users\per\Documents\Arduino\sketch_oct24a\sketch_oct24a.ino:2:3: error: 'foo' was not declared in this scope
   foo();
   ^~~

Namespaces

Prototypes are not generated for functions in namespaces (https://github.com/arduino/Arduino/issues/5984):

https://github.com/arduino/arduino-cli/blob/f23975438ca8ad6463fadf61e181c0bc03a20ae1/legacy/builder/ctags/ctags_parser.go#L167-L169

Compiling a sketch with a function using default parameter values that was referenced before declaration like this:

namespace foo {
  void bar() {
    baz();
  }
  void baz() {}
}
void setup() {
  foo::bar();
}
void loop() {}

will fail:

C:\Users\per\Documents\Arduino\sketch_oct24a\sketch_oct24a.ino: In function 'void foo::bar()':
C:\Users\per\Documents\Arduino\sketch_oct24a\sketch_oct24a.ino:3:5: error: 'baz' was not declared in this scope
     baz();
     ^~~

Arduino CLI knows full well that it is omitting an essential prototype, yet doesn't make any effort to communicate that fact to the user.

🙁 The user will have great difficulty in determining the cause of the error and how to fix it. When the user asks for help on the forum, the programming wizards there will take great glee in the opportunity to gripe once again about how terrible of an idea prototype generation is.

Arduino CLI version

f2397543

Operating system

All

Operating system version

Any

Additional context

Examples of where this has caused confusion for the users:

Additional Requests

https://github.com/arduino/arduino-cli/issues/1944#issuecomment-1290014658

Issue checklist

[X] I searched for previous requests in the issue tracker
[X] I verified the feature was still missing when using the latest nightly build
[X] My request contains all necessary details

arduino / arduino-cli