GitHub PullRequestReviewCommentEvent at 2014-03-31 12:21:34
Repository: RIOT
Actor: Kijewski
Payload: {"comment":{"url":"https://api.github.com/repos/RIOT-OS/RIOT/pulls/comments/11112796","id":11112796,"diff_hunk":"@@ -18,18 +18,61 @@\n #ifndef __RINGBUFFER_H\n #define __RINGBUFFER_H\n \n+/**\n+ * @brief     Ringbuffer.\n+ * @details   Non thread-safe FIFO ringbuffer implementation around a `char` array.\n+ */\n typedef struct ringbuffer {\n-    char *buf;\n-    unsigned int        start;\n-    unsigned int        end;\n-    unsigned int        size;\n-    unsigned int        avail;\n+    char *buf; /**< Buffer to operate on. */\n+    unsigned int start; /**< Current position in the ring buffer */\n+    unsigned int end;   /**< Position after the last available element. */\n+    unsigned int size;  /**< Size of buf. */\n+    unsigned int avail; /**< Number of elements available for reading. */\n } ringbuffer_t;\n \n+/**\n+ * @brief        Initialize a ringbuffer.\n+ * @param[out]   rb        Datum to initialize.\n+ * @param[in]    buffer    Buffer to use by rb.\n+ * @param        bufsize   `sizeof (buffer)`\n+ */\n void ringbuffer_init(ringbuffer_t *rb, char *buffer, unsigned int bufsize);\n+\n+/**\n+ * @brief     Add an element to the ringbuffer.\n+ * @details   If rb is full, then the oldest element gets overwritten.\n+ *            Compare `rb->size < rb->avail` if that is not overwring is not intended.\n+ * @param     rb    Ringbuffer to operate on.\n+ * @param     c     Element to add.\n+ */\n void rb_add_element(ringbuffer_t *rb, char c);\n-void rb_add_elements(ringbuffer_t *rb, char *buf, int n);\n+\n+/**\n+ * @brief     Add a number of elements to the ringbuffer.\n+ * @details   Only so many elements are added as fit in the ringbuffer.\n+ *            No elements get overwritten.\n+ *            If this is not the intended behavior, then use rb_add_element() in a loop instead.\n+ * @param     rb    Ringbuffer to operate on.\n+ * @param     buf   Buffer to add elements from.\n+ * @param     n     Maximum number of elements to add.\n+ * @returns   Number of elements actually added. 0 if rb is full.\n+ */\n+int rb_add_elements(ringbuffer_t *rb, const char *buf, int n);\n+\n+/**\n+ * @brief     Peek and remove oldest element form the ringbuffer.\n+ * @param     rb   Ringbuffer to operate on.\n+ * @returns   The oldest element that was added, or `-1` if rb is empty.","path":"sys/include/ringbuffer.h","position":63,"original_position":63,"commit_id":"e384dfb941a47227e52620ed6a8d91ea4572f758","original_commit_id":"e384dfb941a47227e52620ed6a8d91ea4572f758","user":{"login":"Kijewski","id":136776,"avatar_url":"https://avatars.githubusercontent.com/u/136776?","gravatar_id":"b26d2f162636903c1578cf3c45162845","url":"https://api.github.com/users/Kijewski","html_url":"https://github.com/Kijewski","followers_url":"https://api.github.com/users/Kijewski/followers","following_url":"https://api.github.com/users/Kijewski/following{/other_user}","gists_url":"https://api.github.com/users/Kijewski/gists{/gist_id}","starred_url":"https://api.github.com/users/Kijewski/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Kijewski/subscriptions","organizations_url":"https://api.github.com/users/Kijewski/orgs","repos_url":"https://api.github.com/users/Kijewski/repos","events_url":"https://api.github.com/users/Kijewski/events{/privacy}","received_events_url":"https://api.github.com/users/Kijewski/received_events","type":"User","site_admin":false},"body":"`0` is a valid char.","created_at":"2014-03-31T12:21:34Z","updated_at":"2014-03-31T12:21:34Z","html_url":"https://github.com/RIOT-OS/RIOT/pull/933#discussion_r11112796","pull_request_url":"https://api.github.com/repos/RIOT-OS/RIOT/pulls/933","_links":{"self":{"href":"https://api.github.com/repos/RIOT-OS/RIOT/pulls/comments/11112796"},"html":{"href":"https://github.com/RIOT-OS/RIOT/pull/933#discussion_r11112796"},"pull_request":{"href":"https://api.github.com/repos/RIOT-OS/RIOT/pulls/933"}}}}