I'm interested in the stepper.h library. How does one learn about the commands that are available for a particular library?
In one example sketch, for example, I see the command: stepper.setSpeed(30);
How does one know what the variable limits are, and other options that may be useful.
Obviously, I'm very new to Arduino. I must be missing something very fundamental. I couldn't find anything with a search of the forum. There is lots of information about building a library, but nothing that I could find about using the available ones. Did I search on the incorrect topic?
Start with the documentation if it exists. In this case it does:
All of the official Arduino libraries have their own reference pages:
You're not going to find specific documentation on the forum.
After that the definitive documentation will always be the source code.
To find the source files for any library do this:
File > Examples > open any example from the library you want to find
Sketch > Show Sketch Folder - this will open the example folder inside of the library folder.
Navigate up two folder levels to the root of the library. You will usually find the source files either there or in the src subfolder. You can open the source files in any text editor.
Thanks folks! I'm really quite surprised that there isn't some sort of *.txt file in each library that describes the various calls. One would think this would be the case, at least for the more common stuff, such stepper.h, etc.
Hmmm, being an author, this just calls out for a simple book that describes the calls and what one can do with them.
A Web page might be more appropriate and easier to keep up to date. You are going to keep it up to date I hope ! If only there was a way that anyone could update such a page ...
k1ypp:
Thanks folks! I'm really quite surprised that there isn't some sort of *.txt file in each library that describes the various calls.
Some 3rd libraries do contain documentation files.
Most commonly this would be in a file in the root of the repository named readme (most commonly README.md).
Some libraries use doxygen to generate elaborate documentation in html files. These files will be in a subfolder of the library but there may be a link in the readme.
Some libraries put documentation in the GitHub wiki associated with the repository. The wiki files will not be included with the library files so you need to go to the repository and click on the "Wiki" link. Bitbucket has something similar.
k1ypp:
such stepper.h, etc.
I think most users prefer to use the online reference pages for the official Arduino libraries. There are plans to eventually store the library reference content in the repository of the associated library.
k1ypp:
Hmmm, being an author, this just calls out for a simple book that describes the calls and what one can do with them.
Printing API documentation on paper is not a great idea since APIs change. Some might find a guide to common Arduino libraries useful.
I think you could make a more significant contribution to the Arduino community with less effort by submitting documentation, or documentation improvements where it already exists, to the various libraries.
Most 3rd party libraries are hosted in GitHub repositories so you can simply submit a pull request or just edit directly if it's in a wiki.
The documentation for the official Arduino libraries is not currently on GitHub but you can submit an issue report with your suggested improvements and a member of the Arduino team will eventually make the requested changes. You can find the repositories for the official Arduino libraries here: https://github.com/arduino-libraries
There is certainly a lot of room for improvement.
I didn't see an easy way to reply individually, so here goes:
Delta_G: #5:
Oh, I'm not upstet at all, I'm just amazed that the info is so buried. I'm an electrical engineer (retired) and I wouldn't have dreamed of putting out a product with, at least, a rudimentary user guide. I realize they get nothing out of me using the library, I do appreciate it, but when and if I ever create a library, I'd be certain to include a user document that tells folks what's in it.
UKHeilBob: #6:
Well, I don't know about dead trees, but certainly a Kindle book and PDF. :>)
You are correct about keeping things up to date. At least it should have the basic stuff in it to get one started. In an ebook, one can create a page (online) with links that take the reader to possible sketches, etc.
pert: #7:
I'll sniff around for some of those libraries that have docs. It would be interesting to see how they handle it. I'll check out what you suggest, as time permits. I'm on a tight schedule to get my Arduino project finished so I can get a magazine article off to a publisher. I'm VERY new to Arduino and loving it!
PaulMurryCbr: #8:
Is a foobar a float, or a volitile int? :>)
Thanks everyone for the help, suggestions and ideas. My first published book is about hiking the Appalachian Trail and surviving. I'm currently working on a book about my dad in WW II and another on hiking the Camino in Spain. Doing the research and coming up with an ebook on the library topics could be fun, but will have to wait a while. Then again, my wife is a retired technical writer, maybe I could get her interested?
You must have a better memory than I. I'm the primary beneficiary of the documentation I write and it's certainly worth the effort when I come back to a project after not having used it for some time. I also think writing documentation is a good method of planning before starting coding.
Of course the free software developer is under no obligation to do anything but it is frustrating to me when they don't provide any documentation at all because it's so much easier for them to document the code they write than for all the users to try to figure out how to use that code without the documentation. I think writing good documentation actually saves time in the end by preventing support requests and invalid bug reports.
k1ypp:
My first published book is about hiking the Appalachian Trail and surviving.
Nice! I through hiked the Pacific Crest Trail in 2005 and have always planned to do the Appalachian trail eventually. As time goes on it seems less and less likely that I'll be able to break free for such a long vacation but I can still dream.
k1ypp:
another on hiking the Camino in Spain.
I traveled around some of the northern end in the 90s and was fascinated when I found out what these pilgrims with their scallop shells were doing. I think that was maybe when the idea of doing a long walk first entered my mind.
Delta_G:
That's just it. They didn't "put out a product". They just shared something that they had written for themselves.
IMHO if someone decides to share something they should also provide reasonable documentation - especially if they take the trouble to put it in a library. If they are not prepared to do that, then don't publish.
However there is a big difference between posting a short snippet to illustrate a point and posting a library.
By the way, this lack of documentation is by no means limited to Arduino stuff.
What I often find most frustrating is the absence of advice about what a program is NOT capable of doing or NOT intended for (and, to cut off the wisecracks, I don't mean silly things like "eating breakfast").
Robin2:
IMHO if someone decides to share something they should also provide reasonable documentation - especially if they take the trouble to put it in a library. If they are not prepared to do that, then don't publish.R
hmmm... so who'd decide what was "reasonable documentation" the Ministry of Truth?
Or...
No one is putting a gun to anyone's head forcing them to use their open-sourced code/library. If the user of the code isn't prepared to fully understand what they are using, they have the option not to modify it or even use it at all. Vote with their mouse and keyboard, kind of thing.
The code is the documentation, after all. Undocumented great code is still great code. Documented shit code is still shit code. The key to understanding the code is to speak the language, and there are abundant resources out there to do that.
Most of the hullabaloo around undocumented libraries is generated from people who are still inexperienced using the library (or inexperienced in programming in general). This topic has been debated on this forum ad nauseam, each time instigated by yet another newbie exploring, using code that they don't yet fully understand. That then leads them here, to summon the ruckus yet again... the circle of life.
pert:
Nice! I through hiked the Pacific Crest Trail in 2005 and have always planned to do the Appalachian trail...
Delta_G:
Maybe I used the term "product," too loosely? The ultimate goal of my current Arduino project is to create a "product" that I am preparing for a technical magazine article. In former years I would have filed for a patent, but I too am putting this one out there for free, so that anyone can build it and enjoy. Of all my patents, this is the one that is most interesting. When it is published, I'll drop a note here about it.
Not to get too off topic, the hiking book title is "Three Hundred Zeroes: Lessons of the heart on the AT." My brother and I were going to hike it after our 60's military duty, but he was killed in action in Vietnam. The book ended up an award winning publication, with many thousands of readers. To learn more, see Amazon:
