Go Down

Topic: Variable types in the documentation? (Read 1 time) previous topic - next topic


I was posting something to someone about the tone functionality, and I went to the reference:


His problem was likely that a value he was passing as the frequency was too big for the argument; his number he was passing was 38000, which didn't work, but 30000 did. I surmised (and he figured the same) that it was because the variable was too small (needing a signed integer, likely).

Looking at the reference, though, doesn't tell you anything about the functions arguments; ie, what their type is?

Am I missing something?

I will not respond to Arduino help PM's from random forum users; if you have such a question, start a new topic thread.


Just have a look into the .h file:

Code: [Select]

class Tone
   void begin(uint8_t tonePin);
   bool isPlaying();
   void play(unsigned int frequency, unsigned long duration = 0);
   void stop();

Check out my experiments http://blog.blinkenlight.net


Yes, but I think the OP is suggesting that the docs that are published on the reference page should have the data types specified for all function arguments.



ahdavidson - this is exactly what I am saying.

Udo Klein - I know to do this, yes; but short of downloading the library, unzipping it, etc - to get to that .h file on a computer on which I don't have the Arduino IDE installed doesn't make much sense in order to find out what type a particular argument is.

In the case I mentioned, I was at work, on a computer which didn't have the IDE or the tone library installed, so I went to the doc page, and...no argument types.

Yes, there are other ways, but they may not be available for all libraries, or they would involve more steps than it is worth to answer a simple question; the type definitions should be in the docs...

I will not respond to Arduino help PM's from random forum users; if you have such a question, start a new topic thread.


The down side of including the type in the reference is that the type is usually not needed and many beginners would find its inclusion intimidating.

In my opinion, the friendlier solution would be to add a statement in the reference saying something like:  The highest valid frequency value is 32767


Mar 21, 2010, 03:28 pm Last Edit: Mar 21, 2010, 03:31 pm by ahdavidson Reason: 1
The hard part about tech writing and documentation is always making it both accessible to the novice and useful to the expert.

We could do something like this for function specs:



pinthe pin on which to generate the tonebyte
frequencythe frequency of the tone in hertzint
duration the duration of the tone in millisecondsint

Left as an exercise is how to indicate optional parameters.

While this might be tad intimidating to the novices, I think they will tend to just look at the simple examples to get going.

Btw, take a look at one on the Processing reference page.



Small point.

The header file declaration
Code: [Select]
void play(unsigned int frequency, unsigned long duration = 0); would not lead me to the believe that frequency values must be below 32768, because the value of frequency is an unsigned int. I would assume that values upto 65,535 would be okay.

Hence, I think:
1. the documentation should say that only values upto 'x' (whatever that is) work if we are to understand it
2. adding the type doesn't tell us enough, and
3. I don't believe there is an obstacle to implement tone() slightly differently so that it supports frequencies upto 65,535 KHz which might be handy for folks using some types of ultrasonic emitters.


Go Up