Add documentation

[atesin]

i had to hardly browse the .h file to learn how to fully use this library, so...

please make a public functions list with parameters and maybe a brief explanation

please indicate also some other included libraries (like time.h for example) to go to find additional documentation there

thanks for your work

[smz]

Good day @atesin and thank-you for your feedback.

You're right that functions documentation is lacking, but I hoped that the provided examples could be enough to get one started. I developed this library out of need and once I achieved what I needed, I didn't gave it much further thoughts, sorry.

At this time I'm quite busy with other unrelated personal issues, so I don't see myself investing much time into the documentation effort in the near future, but I'll leave this issue open as a reminder to myself.

Anyway I'm absolutely open to user's contributions, so if you have the time and willingness to add some documentation, please feel free to push a pull-request and I will be happy to add it to the project.

As far as regards the need for the Standard C time library (time.h), I think I made it clear that it is needed. See in the main project page:

Please note that it is absolutely mandatory to have an underlying standard compliant C time library (time.h) as this library uses data types and functions which are defined there.

I also added a reference to the relevant documentation for time.h, which is in ISO/IEC 9899 (C90), section 7.23, page 238. I think documenting the usage of time.h is way beyond the scope of this project.

Many thanks again and best regards,

Sergio Manzi

[atesin]

hi ... i choose your library from many other i searched because its simplicty and it uses standard c avr libraries (thus not reinventing the wheel), what appears light and efficient... sure many other people will return to use it with better documentation (see other similar projects)

i found very clever to using templates to specify i2c library, but many people (like me) are not too familiar with preprocessor... so my suggestion is not to rely so heavily on preprocessor directives in examples to focus more in class functions

additionally, by convention upper camel case is used just for class names, and lower camel case for primitives, objects (instanced classes) and function names; so mixing these could lead to confusions too, would be wise to normalize them, like in this example...

#include <RtcDS3231.h> // you already included <time.h> implicitly
#include <Wire.h>
RtcDS3231<TwoWire> myRtc(Wire);

// all the following are expected to start in lowercase
struct tm myTm;
myRtc.begin();
myRtc.getTime(&myTm);

char strTime[20];
strftime(strTime, 20, "%w %d-%m-%Y %H:%M:%S", &myTm);

// but Serial has some static functions (there is no like "Serial.Print()")
Serial.begin(9600)
Serial.print("Current date is: ");
Serial.println(strTime);
Serial.print("Confirm current year: ");

char userInput[6]
userInput[Serial.readBytesUntil('\n', userInput, 5)] = '\0';

int thisYear= atol(userInput); // from <stdlib.h> included by default, also check "ltoa()"

if ( thisYear != myTm.tm_year )
  Serial.println("Wrong year!");

[atesin]

this is a simple list of public functions of RtcDS3231 class, got with regular expressions

notice since all these starts with uppercase, they are FUNCTIONS not classes or constants

half work done, now only left descriptions and some examples... (and post them all on the wiki)

void Begin()
bool IsDateTimeValid()
bool GetIsRunning()
void SetIsRunning(bool isRunning)
void SetTime(struct tm *now)
void SetTime(time_t *now)
void SetTimeUX(time_t *UXnow)
void SetTimeUX(time_t UXnow)
time_t GetTime()
void GetTime(struct tm *utc_tm)
time_t GetTimeUX()
void GetLocalTime(struct tm *local_tm)
void SetSquareWavePin(DS3231SquareWavePinMode pinMode)
void SetSquareWavePinClockFrequency(DS3231SquareWaveClock freq)
void Enable32kHzPin(bool enable)
void SetAlarmOne(const DS3231AlarmOne& alarm)
void SetAlarmTwo(const DS3231AlarmTwo& alarm)
DS3231AlarmOne GetAlarmOne()
DS3231AlarmTwo GetAlarmTwo()
DS3231AlarmFlag LatchAlarmsTriggeredFlags()
float GetTemperature()
void ForceTemperatureCompensationUpdate(bool block)
int8_t GetAgingOffset()
void SetAgingOffset(int8_t value)