API documentation not up to date

[ybycode]

Hi,

It seems the v2.0.x documentation has not been updated since the signature of the sleep function has changed:

In v1.5.x:

bool sleep(int interrupt, int mode, unsigned long ms=0)

Whereas in v2.0.x:

uint8_t sleep(int interrupt, int mode, unsigned long ms=0);

++

yann

[TheoL]

@ybycode this what I found in the 2.0 API doc on the main page

Sleeping

To save battery it is crucial to sleep you node as much as possible. The node can wake up from external interrupts or by a timer.

The following sleep your radio and Arduino (in PowerDownMode). Wakes up on timer interrupt.

void sleep(unsigned long ms);

ms - Number of milliseconds to sleep.

The following sleeps your radio and Arduino (in PowerDownMode). Wakes up on timer interrupt or from an external interrupt.

See: http://arduino.cc/en/Reference/attachInterrupt for details on modes and which pin is assigned to what interrupt. On Nano/Pro Mini: 0=Pin2, 1=Pin3

bool sleep(int interrupt, int mode, unsigned long ms=0);

interrupt - Interrupt that should trigger the wakeup.
mode - RISING, FALLING, CHANGE
ms - Number of milliseconds to sleep (or 0 to sleep forever).

The sleep method returns true if wake up was triggered by pin change and false means timer woke it up.

int8_t sleep(uint8_t interrupt1, uint8_t mode1, uint8_t interrupt2, uint8_t mode2, unsigned long ms=0);

interrupt1 - First interrupt that should trigger the wakeup.
mode1 - Mode for first interrupt (RISING, FALLING, CHANGE)
interrupt2 - Second interrupt that should trigger the wakeup.
mode2 - Mode for second interrupt (RISING, FALLING, CHANGE)
ms - Number of milliseconds to sleep (or 0 to sleep forever).

Returns the interrupt number if wake up was triggered by pin change and negative if timer woke it up.

[ybycode]

I agree, that's what I read too. But the function call

sleep(int interrupt, int mode, unsigned long ms=0)

doesn't return a boolean anymore, but a uint8_t, but the interrupt number if it was triggered, or -1 if timeout, or -2 if not possible because of a firmware update.

See https://github.com/mysensors/MySensors/blob/development/core/MySensorsCore.h#L252

yann

[mfalkvidd]

The doxygen documentation is correct (says int_8t) but the API documentation still says bool.

Isn't the API documentation generated from Doxygen? @hek could you enlighten us why the documentation differs? What can we do to fix it? A pull request isn't feasible since the code already is correct.

[martinhjelmare]

@mfalkvidd

I think the mysensors site is manually updated.

I suggest looking into converting the site source to github pages, which would enable the whole community helping keeping the site docs up to date.

[hek]

Yes, the site is manually updated (improvements is on its way). Must have missed the sleep updates when doing the overview.

Doxygen is always the best place/most correct place to look. And we'll probably move over to pure doxygen once it covers a majority of the library.