Go Down

Topic: Variable types in the documentation? (Read 973 times) previous topic - next topic

cr0sh

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?

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

Udo Klein

Just have a look into the .h file:

Code: [Select]

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


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

ahdavidson

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

cr0sh

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.

mem

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

ahdavidson

#5
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:

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

gbulmer

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.

HTH
GB-)

Go Up