Pages: [1]   Go Down
Author Topic: Variable types in the documentation?  (Read 942 times)
0 Members and 1 Guest are viewing this topic.
Phoenix, Arizona USA
Offline Offline
Faraday Member
**
Karma: 40
Posts: 5597
Where's the beer?
View Profile
WWW
 Bigger Bigger  Smaller Smaller  Reset Reset

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?

 smiley
Logged

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

0
Offline Offline
Faraday Member
**
Karma: 24
Posts: 3496
20 LEDs are enough
View Profile
WWW
 Bigger Bigger  Smaller Smaller  Reset Reset

Just have a look into the .h file:

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

Udo
Logged

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

Seattle, USA
Offline Offline
Full Member
***
Karma: 0
Posts: 248
View Profile
WWW
 Bigger Bigger  Smaller Smaller  Reset Reset

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
Logged

.andy

Phoenix, Arizona USA
Offline Offline
Faraday Member
**
Karma: 40
Posts: 5597
Where's the beer?
View Profile
WWW
 Bigger Bigger  Smaller Smaller  Reset Reset

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

 smiley
Logged

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

London
Offline Offline
Tesla Member
***
Karma: 10
Posts: 6255
Have fun!
View Profile
 Bigger Bigger  Smaller Smaller  Reset Reset

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
Logged

Seattle, USA
Offline Offline
Full Member
***
Karma: 0
Posts: 248
View Profile
WWW
 Bigger Bigger  Smaller Smaller  Reset Reset

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
[/b]
NameDescriptionType
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.

.andy
« Last Edit: March 21, 2010, 09:31:31 am by ahdavidson » Logged

.andy

UK
Offline Offline
God Member
*****
Karma: 0
Posts: 710
Arduino is Genius
View Profile
 Bigger Bigger  Smaller Smaller  Reset Reset

Small point.

The header file declaration
Code:
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.

HTH
GB-)
Logged

Pages: [1]   Go Up
Jump to: