RFC: wdog documentation updates

[Kleist]

I'm working on integrating watchdogd in an embedded Linux project, have some ideas for small updates to the documentation of the wdog API that I would like to contribute. The reason is that i had to dig into the code and examples to understand how to use it. So I'd like to verify that my understanding of the API is correct and make sure that it is documented.

Just wanted to make sure such changes are welcome before I do the actual work?

I would like to document the parameters and return codes from wdog_subscribe / wdog_unsubscribe / wdog_kick, since it is not clear in the current wdog.h or README.md.
I couldn't find any documentation thread safety is not documented. Am I correct to assume that multiple threads can use the wdog API safely as long as they don't share int id and int ack variables?

Do you have any preference for the format of such updates to the comments in wdog.h? I would propose Doxygen style like this:

/*!
 * Kick the watchdog
 * \param id The ID returned from wdog_subscribe
 * \param ack Pointer to the last ACK received from wdog_subscribe or wdog_*kick*. Will be updated with new ACK.
 * \return 0 on success, negative on error (will also set errno)
 */
int   wdog_kick2            (int id, unsigned int *ack);

[troglobit]

I'm working on integrating watchdogd in an embedded Linux project, have some ideas for small updates to the documentation of the wdog API that I would like to contribute. The reason is that i had to dig into the code and examples to understand how to use it. So I'd like to verify that my understanding of the API is correct and make sure that it is documented.

Cool, documentation could definitely be improved upon!

Just wanted to make sure such changes are welcome before I do the actual work?

Of course! :)

I would like to document the parameters and return codes from wdog_subscribe / wdog_unsubscribe / wdog__kick_, since it is not clear in the current wdog.h or README.md. I couldn't find any documentation thread safety is not documented. Am I correct to assume that multiple threads can use the wdog API safely as long as they don't share int id and int ack variables?

Yes.

Do you have any preference for the format of such updates to the comments in wdog.h?

Yes, I do.

I would propose Doxygen style like this:

/*!
 * Kick the watchdog
 * \param id The ID returned from wdog_subscribe
 * \param ack Pointer to the last ACK received from wdog_subscribe or wdog_*kick*. Will be updated with new ACK.
 * \return 0 on success, negative on error (will also set errno)
 */
int   wdog_kick2            (int id, unsigned int *ack);

I'd rather see something like this, which I use in most other projects, e.g. libnet

/**
 * Kick the watchdog
 * @param id The ID returned from wdog_subscribe()
 * @param ack Pointer to the last ACK received from wdog_subscribe() or this function.  Will be updated with new ACK.
 * @return 0 on success, negative on error (also sets @param errno)
 */
int   wdog_kick2            (int id, unsigned int *ack);

[Kleist]

Thank you for the quick reply. I'll make a pull request with the changes.

[troglobit]

Took a while, but now the docs are up and updated at https://codedocs.xyz/troglobit/watchdogd/wdog_8h.html and just in time for the holidays there's a release coming as well 🎅🎁