Maybe I have not searched well enough, but I miss clear explanations of contributed libraries. Especially now that I haven't done anything with Arduino for some time.
I would very much like to see a doc in each library folder that gave a clear explanation of the various functions in the library. Now one has to distill more or less from the examples what functions are available.
In case this exists and I just haven't found it (also not on Github), can someone please point me in the right direction then? Or should I ask this on Github?
Thnx!
Jaap
If documentation exists then its normally to be found in the library itself, often as a ReadMe file. Sometimes comments on use are added the the library or program files themselves, or are on teh GITHUB.
Its up to the writer of the library to add the documentation, and documentation can take up a great deal of time to write, so it may not be as complete as it could be.
Bear in mind that most libraries are provided free of charge.
I generally check to .h first to figure out what sort of basic functionality the library provides via function names. The .h is also a good place to look if you're curious about information on arguments/returns of a particular function.
I look at the .cpp if I need to know the details of exactly HOW a function works.
Generally, any documentation you would see on GitHub is also in the library folder on your computer, since it is those files that provide the content displayed on GitHub.
There are two exceptions:
On many GitHub repositories, you will see at tab at the top of the GitHub pages labeled "Wiki". Often you will find this tab does nothing because there is no wiki but the repository owner is too lazy/incompetent to disable the useless "red herring" wiki tab. However, sometimes you will discover a hidden treasure trove of documentation in the wiki. You would expect a link in the readme to the wiki but all too often I have found that nobody was considerate enough to do so.
At the top of the home page of the repository there is the repository description. Sometimes this contains a link to documentation on an external website. Again, you'd expect that link to also be provided in the readme, but that doesn't always happen.
Some libraries have doxygen documentation that is generated automatically from the source code. This documentation will be in HTML files in a subfolder (I think it's usually called "doc") of the repository and often there is no mention of their existence in the readme. Ideally, there would be manually created documentation text in specially formatted comments in the source code but often the developers don't make that effort and just let doxygen generate the bare minimum skeleton of the documentation from the code itself, which I find to be completely useless. However, with a reasonable amount of effort a considerate developer can produce useful documentation via doxygen.
If you're really desperate, you could check the url value in the library.properties file (if present) in the root folder of the repository. Usually this URL will just point to the library repository, but it might also point to some external website with documentation. There also might be links in the heading of the source files, most likely the .h file.
srnet:
Bear in mind that most libraries are provided free of charge.
I think that the developer does this library making job from the very point of 'social technical responsibility'. Therefore, the developer also thinks that the works what he has done should serve the users in the best amicable way. Unfortunately, it does not always do. For example:
I take the help of RTClib.h Library for the operation of DS3231 RTC Module. To operate my RTC, I include the following lines in my sketch:
I know that the object is created from the class. Here my object is rtc and the class is RTClib. Therefor, my code should be like this: RTClib rtc;. Why is it like this: RTC_DS3231 rtc;. I could never figure it out having done exploration in the RTClib.h. Someone of this Forum may kindly explain it.
GolamMostafa:
Therefor, my code should be like this: RTClib rtc;. Why is it like this: RTC_DS3231 rtc;. I could never figure it out having done exploration in the RTClib.h. Someone of this Forum may kindly explain it.
The question coming from you is confusing, anyway, you need to create the object before you can reference any of the functions (you know that much), The RTClib provides support for different types of units (DS1307, DS3231, PCF8523) , so by creating an RTC_DS3231 object you will have access to the DS3231 specific functions. The name is of the object is of course irrelevant it could just as well be RTC_DS3231 theUnit; Anyway, there is no class in the RTClib.h file that is called RTClib. That is just the name of the file. (which in fact could be anything)
Deva_Rishi:
The name is of the object is of course irrelevant it could just as well be RTC_DS3231 theUnit; Anyway, there is no class in the RTClib.h file that is called RTClib. That is just the name of the file. (which in fact could be anything)
But -- I see the following; where, the class name has followed the library name. The deviation is for the RTClib's case.
Well that you call your object rtcDS3231 has no meaning, however there are libraries that are setup in such a way that there is 1 main class and within the constructor (don't hold me on exact terminology) take the unit specification as an argument and if they author of the library would have chosen this option, it could have looked like this RTClib theObject = RTClib (DS3231); or using a template which would look like this RTClib theObject; It is just the way it is setup.
@GolamMostafa, you are quite confused. RTClib.h is simply the name of the file that you #include in your source code. There is no requirement that it have the same name as the class(es) declared within. If you look inside that file, you'll see multiple class declarations:
class RTC_PCF8523 {
class RTC_DS3231 {
class RTC_DS1307 {
etc.
Those are the classes from which you construct your rtc objects.
gfvalvo:
If you look inside that file, you'll see multiple class declarations:
class RTC_PCF8523 {
class RTC_DS3231 {
class RTC_DS1307 {
Those are the classes from which you construct your rtc objects.
Now, I have known the source of class RTC_DS3231 from which the object rtc has been created. It was my lack of full efforts to see the details of the RTClib.h Library to discover that the library indeed contained classes which you had shown in the above quote.
I had also one more misunderstanding that the classes were always named after the library names (though some are there like: MPU6050.h ===> MPU6050 mpu;) -- this is not a rule as has been cleared up from the example of RTClib.h Library.
Thank you very much for taking time to clarify the issue for my better education. (+)
Deva_Rishi:
Anyway, there is no class in the RTClib.h file that is called RTClib.
But there is an RTClib class in the DS3231.h library: that confused the sh!t out of me until I looked inside them.
These lines below are from ds3231. Note particularly the lines between the comments I have marked XXXXX which makes me wonder if an early RTClib.h did actually originally contain a class of that name?
/*
* DS3231.h
*
* Arduino Library for the DS3231 Real-Time Clock chip
*
* (c) Eric Ayars
* 4/1/11
* released into the public domain. If you use this, please let me know
* (just out of pure curiosity!) by sending me an email:
* [email protected]
*
*/
// Modified by Andy Wickert 5/15/11: Spliced in stuff from RTClib XXXXXXXXX
#ifndef DS3231_h
#define DS3231_h
// Changed the following to work on 1.0
//#include "WProgram.h"
#include <Arduino.h>
#include <Wire.h>
// DateTime (get everything at once) from JeeLabs / Adafruit
// Simple general-purpose date/time class (no TZ / DST / leap second handling!)
class DateTime {
public:
DateTime (uint32_t t =0);
DateTime (uint16_t year, uint8_t month, uint8_t day,
uint8_t hour =0, uint8_t min =0, uint8_t sec =0);
DateTime (const char* date, const char* time);
uint16_t year() const { return 2000 + yOff; }
uint8_t month() const { return m; }
uint8_t day() const { return d; }
uint8_t hour() const { return hh; }
uint8_t minute() const { return mm; }
uint8_t second() const { return ss; }
uint8_t dayOfTheWeek() const;
// 32-bit times as seconds since 1/1/2000
long secondstime() const;
// 32-bit times as seconds since 1/1/1970
// THE ABOVE COMMENT IS CORRECT FOR LOCAL TIME; TO USE THIS COMMAND TO
// OBTAIN TRUE UNIX TIME SINCE EPOCH, YOU MUST CALL THIS COMMAND AFTER
// SETTING YOUR CLOCK TO UTC
uint32_t unixtime(void) const;
protected:
uint8_t yOff, m, d, hh, mm, ss;
};
class RTClib {
public:
// Get date and time snapshot
static DateTime now();
};
// Eric's original code is everything below this line XXXXXXX
class DS3231 {
public:
Wow! Looks like I started quite a discussion here.....
Just ran into exactly what I meant when I started this. Here it is:
On internet I found a neat little sketch that would send data of a DHT11 to a receiver, both using an ATTiny85. (https://www.instructables.com/id/Receiving-and-sending-data-between-Attiny85/)
Great! However......some time ago my old library for the DHT was replaced/updated to "DHT Sensor Library".
So sure enough the compiler found errors as the sketch apparently used the old library. And now I need to figure out how to correct the sketch for it to run with the new library..............Reinstalling the old library is probably not a good idea as it may cause overlaps with the new one.....
This drives me crazy!
From the discussion here I picked up that I could look into the .h file (I guess with a simple text editor like notepad?). I am going to try that.
JB47:
I guess with a simple text editor like notepad?
Yes, it's just a text file so any text editor will work. However, don't ever use Notepad to edit source code files. The reason is it will corrupt the encoding of the file and cause it to no longer work (Microsoft being Microsoft). There are many excellent free text editor programs that are suitable for programming Notepad++ is the one I use, bot others will work as well.
Thanks pert! I will look at this Notepad++, however I won't dare to change anything in source code. I looked at the various .h and .ccp files in the sensor library and although tjat looks interesting enough, it's too much abacadabra for me.....I have trouble enough finding the clues there for adjustment of the sketch. Sofar without success.
Just installed Notepad++ and looked once more at the ccp and h files of the library. WOW! Now this makes sense as in Notepad++ the abacadabra turns into nice lines and text!
THANKS again pert!
JB47:
Thanks pert! I will look at this Notepad++, however I won't dare to change anything in source code. I looked at the various .h and .ccp files.
Try and copy and rename the library first, and change the references to it (the #include and #ifndef) so the changes you make are to "your' new library. and then include that instead to your sketch