Would it be possible to write simple examples ?
And would it be possible to write the documentation so, that the novice understands them ?
Take for example 'substring':
The documentation tells, that it is used like 'string.substring(start,end)'. but forgets to mention, that the value will be dropped to another variable like: 'newstring=string.substring(start.end);
For an example there is a page with picture of a board and some screenshots.
The piece of interest is burrowed in the long program as a piece of code, which takes a novice some time to comprehend:
if (stringOne.substring(19) == "html") {
Serial.println("It's an html file");
}
I have been a professional programmer for about 50 years and used about every programming language and environment there has been. I have also written tens of manuals and user manuals for programs and laboratory devices.
Still I do not like the style of some programmers. It seems that it is more important to show how intelligent they are, than help others and make information usefull.
I am always comparing these 'documents' and 'examples' to the user manuals of VIC-20 and QBasic.
The problem with examples is that you do not know what the reader already knows.
Take
newstring=string.substring(start.end);
Can we assume that the reader knows what the assignment operator does as opposed to the comparison operator ? If not then we have to explain the meaning of it.
Can we assume that the user knows what a variable is ? If not then this needs explaining, which will need to include mention of declaring the target variable and variable types
Can we assume that the user knows how to declare a variable and the implications of using the correct variable type ? If not then we need to explain it which should include mention of variable scope
Can we assume that the reader understands variable scope ? If not then we need to explain variable scope
Somewhere along the line, we probably should explain why the subString() function is proceeded by a full stop, but do you really want to get into explaining OOP ?
With all of that in mind, please provide an explanation of what
newstring=string.substring(start.end);
does without making any assumptions. If you don't put some limits on it then explaining a single function can turn into a full blown course on C++
Is it easier for a newbie to build examples, where the thing in subject is burrowed to some fancy code than a simple case.
Your answer describes a sittuation, where the builder of the example tries to collect all the intelligence and knowledge to her description of the case.
It is obviously easier to understand an example if the subject of the example is not buried in complicated code. However, I think that reinforces my point that you cannot rely on the reader knowing anything
I have to agree that that particular documentation is quite grim. For one thing it does not tell you that the characters in the string are numbered from 0. A new user might assume that the first character in the String has the index of 1.
It is another example of expecting that the reader will know something that you cannot be sure of and hence needs to be explained. As such, it is flawed and it misses the chance to explain it. But, once again, how much can you/should you expect the reader to know ?
This is a difficult area. In one guide that I wrote I included the following text
In the sample programs below there are some assumptions made as follows :
You know how to set the pinMode() of an input and output
Pins A1, A2 and A3 are used as digital inputs but any pin other than 0 and 1 can be used.
Input pins are defined as INPUT_PULLUP in pinMode() and that closing the associated switch takes the pin LOW
Pins 10, 11, 12 and 13 each have LEDs attached via a current limiting resistor to 5V, so taking the pin LOW turns on the LED
Pins 10 and 11 are capable of PWM output when required.
Variables used will be declared as globals for ease of use but purists may want to declare some of them locally
The programs in this thread have been written and tested on a Uno but will run on most/all Arduino boards
It is difficult. That I acknowledge. A reference manual is not a training guide or an introduction to basic concepts and we can be grateful at least someone has taken some trouble to document something.
However, a better job could have been done with the examples to make things a bit clearer, especially in the areas where assumptions have to made if it is not specified or there are differences across languages (which may catch otherwise experienced users), such as:
Does the character numbering start at 0 or 1
Is the "end" parameter an index or offset of the last character or is it the index of the character following the last character or is it an absolute number of characters.
Here is the visual basic MID function which acts a bit like the Arduino substring method of the String class, but the parameters have a completely different meaning. However, there are enough well chosen examples to make it clear what the parameters mean.
This example uses the Mid function to return a specified number of characters from a string.
' Creates text string.
Dim testString As String = "Mid Function Demo"
' Returns "Mid".
Dim firstWord As String = Mid(testString, 1, 3)
' Returns "Demo".
Dim lastWord As String = Mid(testString, 14, 4)
' Returns "Function Demo".
Dim midWords As String = Mid(testString, 5)
substring() has a strange interface, at least to me. It seems more typical to specify the number of characters to extract, rather than the endpoint. It also swaps left and right if you do substring (5,3) for example.
substring() is inherited from Wiring, for comparison here is the Wiring reference;
Indeed. But you have to know that "start" begins at 0 which is made clear here, for example: PHP substr() Function . Other languages may have other rules as in the case of, for example, visual basic. A few carefully chosen examples will show this.