[riot-notifications] [RIOT-OS/RIOT] drivers/rtc: Improved documentation (#11360)

Marian Buschsieweke notifications at github.com
Tue Apr 9 12:00:00 CEST 2019


maribu commented on this pull request.



> @@ -74,9 +76,11 @@ int rtc_get_time(struct tm *time);
  * @param[in] cb            Callback executed when alarm is hit.
  * @param[in] arg           Argument passed to callback when alarm is hit.
  *
- * @return  0 for success
- * @return -2 invalid `time` parameter
- * @return -1 other errors
+ * @retval  0               Success
+ * @retval -EINVAL          @p time or @p cb is `NULL`
+ * @retval -EINVAL          @p time does not contain a valid time
+ * @retval -ETIME           @p time refers to the past (alarm would never trigger)

No error code fully matches this. These would be the closes matches:

| Error Code | Output of `strerror(errno)`                    |
|:---------- |:---------------------------------------------- |
| `ETIME`    | Timer expired                                  |
| `EINVAL`   | Invalid argument                               |
| `EDOM`     | Mathematics argument out of domain of function |

The best match would be `-EINVAL` for timers in the past. But I think there is value if the caller is able to distinguish the causes for the fault.

> @@ -85,8 +89,10 @@ int rtc_set_alarm(struct tm *time, rtc_alarm_cb_t cb, void *arg);
  *
  * @param[out]  time        Pointer to structure to receive alarm time
  *
- * @return  0 for success
- * @return -1 an error occurred
+ * @retval  0               Success
+ * @retval -EINVAL          @p time is `NULL`
+ * @retval -ENODATA         No alarm is pending

No error code fully matches this. These would be the closes matches:

| Error Code | Output of `strerror(errno)`                           |
|:---------- |:----------------------------------------------------- |
| `ETIME`    | Timer expired                                         |
| `ENODATA`  | No message is available on the STREAM head read queue |
| `ENOENT`   | No such file or directory                             |
| `ENOMSG`   | No message of the desired type                        |

All of these are pretty poor choices when looking at the error code description, but for `ENODATA` at least the name of the error code is somewhat fitting.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/RIOT-OS/RIOT/pull/11360#pullrequestreview-224303626
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20190409/ef911cb3/attachment.html>


More information about the notifications mailing list