Hi there!
I think it would be helpful if the signatures of Arduino's functions were mentioned in the Reference section.
What do you think?
Regards,
Gregor
gregorss:
I think it would be helpful if the signatures of Arduino's functions were mentioned in the Reference section.
I'm having a particularly blond moment, what signatures are you referring to?
Riva:
I'm having a particularly blond moment, what signatures are you referring to?
Presumably the names of the guys that wrote the functions?
...R
Riva:
I'm having a particularly blond moment, what signatures are you referring to?
I am talking about something like
int foo(char*)
which tells me that the function named foo requires a char* parameter and returns an int.
Why I'm missing this info: There was a question in the german section that had to do with delay(). So I wanted to find out what kind/size of parameter delay() exactly requires. Since I don't know where the header files for the Arduino language are located I thought I might find this information in the reference section. And since the (printed) reference of the C++ language that I have does show this information with every function that is mentioned there, I think such information should be a compulsory part of a function documentation.
Regards,
Gregor
Okay, I understand now and think it's a good idea to include in the reference pages.
Just in case they don't you can find the main points in the Arduino.h file and they are...
typedef unsigned int word;
#define bit(b) (1UL << (b))
typedef uint8_t boolean;
typedef uint8_t byte;
void init(void);
void initVariant(void);
int atexit(void (*func)()) __attribute__((weak));
void pinMode(uint8_t, uint8_t);
void digitalWrite(uint8_t, uint8_t);
int digitalRead(uint8_t);
int analogRead(uint8_t);
void analogReference(uint8_t mode);
void analogWrite(uint8_t, int);
unsigned long millis(void);
unsigned long micros(void);
void delay(unsigned long);
void delayMicroseconds(unsigned int us);
unsigned long pulseIn(uint8_t pin, uint8_t state, unsigned long timeout);
void shiftOut(uint8_t dataPin, uint8_t clockPin, uint8_t bitOrder, uint8_t val);
uint8_t shiftIn(uint8_t dataPin, uint8_t clockPin, uint8_t bitOrder);
void attachInterrupt(uint8_t, void (*)(void), int mode);
void detachInterrupt(uint8_t);
uint16_t makeWord(uint16_t w);
uint16_t makeWord(byte h, byte l);
#define word(...) makeWord(__VA_ARGS__)
unsigned long pulseIn(uint8_t pin, uint8_t state, unsigned long timeout = 1000000L);
void tone(uint8_t _pin, unsigned int frequency, unsigned long duration = 0);
void noTone(uint8_t _pin);
// WMath prototypes
long random(long);
long random(long, long);
void randomSeed(unsigned int);
long map(long, long, long, long, long);
The parameter type is documented for delay():
https://www.arduino.cc/en/Reference/Delay
Parameters
ms: the number of milliseconds to pause (unsigned long)
I believe this wasn't always the case and may still be missing on some of the reference pages. What's not documented that I think should be added is the return types. Of course there's no need with delay() but other functions it could be useful.
I don't like the function signature style of documentation for this usage because it's not very beginner friendly and that is the specific goal of the Arduino reference pages. So in this usage I think the style of documentation Arduino uses is good but I don't think hiding information makes it more user friendly.
I would also format it a bit differently. Instead of mashing the return type on the end of the line in parentheses I would put it on its own line, something like:
ms: the number of milliseconds to pause
type: unsigned long