Variable types in the documentation?

Forum 2005-2010 (read only) General Uno Punto Zero
1

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

http://arduino.cc/en/Reference/Tone

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?

:slight_smile:

2

Just have a look into the .h file:

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

Udo

3

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.

.andy

4

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...

:slight_smile:

5

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

6

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:

Parameters

Name Description Type
pin the pin on which to generate the tone byte
frequency the frequency of the tone in hertz int
duration the duration of the tone in milliseconds int

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.

.andy

7

Small point.

The header file declarationvoid 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.

HTH
GB-)