Where is the "vocabulary" to the Libraries?

Adafruit Ethernet, Motor, Proto, Wave, Datalogger, GPS Shields - etc!

Moderators: adafruit_support_bill, adafruit

Please be positive and constructive with your questions and comments.
Locked
afterthought
 
Posts: 27
Joined: Fri May 03, 2013 2:18 pm

Where is the "vocabulary" to the Libraries?

Post by afterthought »

Where does one find the available procedures, functions in a Library with some explanation of what they do?

(Like in the Adafruit_CC3000 Library : Adafruit_CC3000_Client ,cc3000.connectToAP, cc3000.checkDHCP(). What else is available? What do they do?
The Tutorials give a good introduction to the available procedures of a Library but they do not reveal all available procedures.

I am sure there is a well known answer to this question-I just don't know it.
Could somebody advise?

1chicagodave
 
Posts: 564
Joined: Wed Jun 19, 2013 3:35 am

Re: Where is the "vocabulary" to the Libraries?

Post by 1chicagodave »

If you want answers... go to the source.

You can open up the .h and .cpp files in a text editor and read through them. They should contain all the classes & methods used and sometimes even some decent comments explaining them.

afterthought
 
Posts: 27
Joined: Fri May 03, 2013 2:18 pm

Re: Where is the "vocabulary" to the Libraries?

Post by afterthought »

Thanks! I found it. (Not much explanation-it must be self explanatory to most of you,I will try to catch up)

1chicagodave
 
Posts: 564
Joined: Wed Jun 19, 2013 3:35 am

Re: Where is the "vocabulary" to the Libraries?

Post by 1chicagodave »

I've never used the CC3000. But, from a quick glance at the files, it is one of the better documented libraries I've seen. (That's not saying much, though.)
From the format of the comments...there may be an html-esque doc file somewhere...?

It's really just about learning a bit of C - C++, and figuring things out based on context.
When I try to learn a new hardware-specific library, I'll typically have multiple tabs open in my web browser.
- GitHub with header file (.h)
- GitHub with source file (.cpp)
- Hardware Datasheet
cplusplus.com
- Maybe an example sketch

When I see something I don't understand, or want to learn more about, I start searching through to find (ctrl-f) how it's used or what it does. Then add my own comments in to help me remember what I found.

Good luck!

User avatar
ss32
 
Posts: 22
Joined: Mon Mar 25, 2013 4:30 pm

Re: Where is the "vocabulary" to the Libraries?

Post by ss32 »

I'm having the same problem with the PN532. They referred me to the datasheet but I'm not seeing how their header commands match up with anything in the data sheet.

1chicagodave
 
Posts: 564
Joined: Wed Jun 19, 2013 3:35 am

Re: Where is the "vocabulary" to the Libraries?

Post by 1chicagodave »

ss32 wrote:I'm having the same problem with the PN532. They referred me to the datasheet but I'm not seeing how their header commands match up with anything in the data sheet.
On this page there are also links to User Manual & App Note.
http://www.adafruit.com/products/364#Learn

Those should bear more fruit than the Datasheet.

User avatar
ss32
 
Posts: 22
Joined: Mon Mar 25, 2013 4:30 pm

Re: Where is the "vocabulary" to the Libraries?

Post by ss32 »

The thing that gets me is that Adafruit wrote the libraries for their card and the commands are based off manuals/datasheets that weren't produced by them so there's a disconnect there. I just wish the libraries came with explicit definitions for the commands.

ennbr
 
Posts: 26
Joined: Sun Feb 12, 2012 12:17 pm

Re: Where is the "vocabulary" to the Libraries?

Post by ennbr »

ss32,

I agree years ago it was common place to provide a Doc file with all libraries containing at minim.

Function name()
Passed parameters
Return values
etc...

Also it was common to have short examples of usage for each library function included within the Doc. The user should NOT be required to search a header file or source to find information needed to implement the library. Although examples are provided in most cases they don't exercise all functionality of the library. It would be helpful to see at a glance all library capabilities without searching through the source code.

Just my 2 cents...

1chicagodave
 
Posts: 564
Joined: Wed Jun 19, 2013 3:35 am

Re: Where is the "vocabulary" to the Libraries?

Post by 1chicagodave »

ennbr wrote: Although examples are provided in most cases they don't exercise all functionality of the library. It would be helpful to see at a glance all library capabilities without searching through the source code.

Just my 2 cents...
I agree.

And, I hope this doesn't sound argumentative...I just have a few small additions.

The great thing about everything here being open-source is that users can always add some documentation or helpful examples of functions, submit a pull-request, and have it added for everyone's benefit. If it wasn't all open-source...that'd be a different story.

Even the least documented library with minimal example code is still considerably more than many others (that I've found) whom sell these types of components and breakout boards provide. And, this forum exists to fill in the holes that do exist.

I believe Adafruit's mission is more set toward inspiring people to learn about electronics & make cool things and then providing whatever products & information they think best help with that, as opposed to just selling a complete solution for specific purpose. I'm relatively new to a lot of this stuff, and having to go through datasheets & libraries to figure out how things work forced me to learn a lot more, much quicker, than I would've by just reading a manual of sorts.

I also appreciate that some people just don't have the time to spend doing that, or might not know to look for other features that may be available. So, it's pretty cool that so many knowledgable people come to this forum willing to answer questions and help others out. :)
I agree years ago it was common place to provide a Doc file with all libraries containing at minim.

Function name()
Passed parameters
Return values
etc...
I've recently been playing with 'Doxygen', an extension for Visual Studio & Atmel Studio. It does a rather nice job of creating a clickable html version of just that. It can also incorporate & associate comments into the doc. I've actually been working on commenting up a few of the libraries I use to create useful Doxygen doc files to post online to maybe help others.

- Dave

User avatar
adafruit_support_mike
 
Posts: 67446
Joined: Thu Feb 11, 2010 2:51 pm

Re: Where is the "vocabulary" to the Libraries?

Post by adafruit_support_mike »

1chicagodave wrote:I believe Adafruit's mission is more set toward inspiring people to learn about electronics & make cool things and then providing whatever products & information they think best help with that, as opposed to just selling a complete solution for specific purpose.
That's it in a nutshell. Ladyada has described Adafruit as "an education company that just happens to have a gift shop at the end". We want you to read the code in the libraries, and we want you to read the datasheets.

It's a relatively gentle way to introduce people to the Open Source and Open Hardware mindset. When the people who develop technology restrict access to and use of their creation, you have to petition the owner for anything nonstandard, and usually pay a healthy fee to get it. OTOH, people have a right to demand services they've had to pay for because they aren't allowed to do the work for themselves.

OSS/OHW remove the access and use restrictions, but in the process they also limit the amount a third party can demand from the original creator. The issue has been argued over and over again, but tends to stop at the questions, "how much Open code/hardware do you currently maintain?" and "If you want something that doesn't exist, what's stopping you from creating it and releasing/maintaining it yourself?"

That sounds harsh the first time you hear it, but it's a central tenet of the Maker/OSS/OHW mindset.

Locked
Please be positive and constructive with your questions and comments.

Return to “Arduino Shields from Adafruit”