[media] dvb_ringbuffer.h: document the define macros

There are a few define macros not documented, because the ReST
output was causing more warnings.

Now that this got fixed, document them. While here, fix the
remaining coding style issues.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>

diff --git a/drivers/media/dvb-core/dvb_ringbuffer.h b/drivers/media/dvb-core/dvb_ringbuffer.h
index f64bd86fe5fd39032a2d31369011993c138ad3b7..eae3f091b6a0928bd64b3d7bebec04e942b9956f 100644 (file)
--- a/drivers/media/dvb-core/dvb_ringbuffer.h
+++ b/drivers/media/dvb-core/dvb_ringbuffer.h
@@ -97,7 +97,6 @@ extern ssize_t dvb_ringbuffer_avail(struct dvb_ringbuffer *rbuf);
  */
 extern void dvb_ringbuffer_reset(struct dvb_ringbuffer *rbuf);
 
-
 /*
  * read routines & macros
  */
@@ -117,11 +116,21 @@ extern void dvb_ringbuffer_flush(struct dvb_ringbuffer *rbuf);
  */
 extern void dvb_ringbuffer_flush_spinlock_wakeup(struct dvb_ringbuffer *rbuf);
 
-/* DVB_RINGBUFFER_PEEK - peek at byte @offs: in the buffer */
+/**
+ * DVB_RINGBUFFER_PEEK - peek at byte @offs in the buffer
+ *
+ * @rbuf: pointer to struct dvb_ringbuffer
+ * @offs: offset inside the ringbuffer
+ */
 #define DVB_RINGBUFFER_PEEK(rbuf, offs)        \
-                       (rbuf)->data[((rbuf)->pread + (offs)) % (rbuf)->size]
+                       ((rbuf)->data[((rbuf)->pread + (offs)) % (rbuf)->size])
 
-/* advance read ptr by @num: bytes */
+/**
+ * DVB_RINGBUFFER_SKIP - advance read ptr by @num bytes
+ *
+ * @rbuf: pointer to struct dvb_ringbuffer
+ * @num: number of bytes to advance
+ */
 #define DVB_RINGBUFFER_SKIP(rbuf, num) {\
                        (rbuf)->pread = ((rbuf)->pread + (num)) % (rbuf)->size;\
 }
@@ -155,12 +164,16 @@ extern ssize_t dvb_ringbuffer_read_user(struct dvb_ringbuffer *rbuf,
 extern void dvb_ringbuffer_read(struct dvb_ringbuffer *rbuf,
                                   u8 *buf, size_t len);
 
-
 /*
  * write routines & macros
  */
 
-/* write single byte to ring buffer */
+/**
+ * DVB_RINGBUFFER_WRITE_BYTE - write single byte to ring buffer
+ *
+ * @rbuf: pointer to struct dvb_ringbuffer
+ * @byte: byte to write
+ */
 #define DVB_RINGBUFFER_WRITE_BYTE(rbuf, byte)  \
                        { (rbuf)->data[(rbuf)->pwrite] = (byte); \
                        (rbuf)->pwrite = ((rbuf)->pwrite + 1) % (rbuf)->size; }
@@ -194,7 +207,6 @@ extern ssize_t dvb_ringbuffer_write(struct dvb_ringbuffer *rbuf, const u8 *buf,
 extern ssize_t dvb_ringbuffer_write_user(struct dvb_ringbuffer *rbuf,
                                         const u8 __user *buf, size_t len);
 
-
 /**
  * dvb_ringbuffer_pkt_write - Write a packet into the ringbuffer.
  *
@@ -265,5 +277,4 @@ extern void dvb_ringbuffer_pkt_dispose(struct dvb_ringbuffer *rbuf, size_t idx);
 extern ssize_t dvb_ringbuffer_pkt_next(struct dvb_ringbuffer *rbuf,
                                       size_t idx, size_t *pktlen);
 
-
 #endif /* _DVB_RINGBUFFER_H_ */