[vlc-commits] network/io: move documentation to header file

[Rémi Denis-Courmont]

vlc | branch: master | Rémi Denis-Courmont <remi at remlab.net> | Fri Nov  9 22:44:28 2018 +0200| [0463c0bc9b99c0aa10fc442215077427b5cab6c5] | committer: Rémi Denis-Courmont

network/io: move documentation to header file

> http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=0463c0bc9b99c0aa10fc442215077427b5cab6c5
---

 include/vlc_network.h | 34 +++++++++++++++++++++++++++++++++-
 src/network/io.c      | 25 -------------------------
 2 files changed, 33 insertions(+), 26 deletions(-)

diff --git a/include/vlc_network.h b/include/vlc_network.h
index 12417eb7d1..9c77b7b168 100644
--- a/include/vlc_network.h
+++ b/include/vlc_network.h
@@ -182,14 +182,46 @@ int net_Subscribe (vlc_object_t *obj, int fd, const struct sockaddr *addr,
 
 VLC_API int net_SetCSCov( int fd, int sendcov, int recvcov );
 
+/**
+ * Reads data from a socket.
+ *
+ * This blocks until all requested data is received
+ * or the end of the stream is reached.
+ *
+ * This function is a cancellation point.
+ * @return -1 on error, or the number of bytes of read.
+ */
 VLC_API ssize_t net_Read( vlc_object_t *p_this, int fd, void *p_data, size_t i_data );
 #define net_Read(a,b,c,d) net_Read(VLC_OBJECT(a),b,c,d)
+
+/**
+ * Writes data to a socket.
+ *
+ * This blocks until all data is written or an error occurs.
+ *
+ * This function is a cancellation point.
+ *
+ * @return the total number of bytes written, or -1 if an error occurs
+ * before any data is written.
+ */
 VLC_API ssize_t net_Write( vlc_object_t *p_this, int fd, const void *p_data, size_t i_data );
 #define net_Write(a,b,c,d) net_Write(VLC_OBJECT(a),b,c,d)
+
+/**
+ * Reads a line from a file descriptor.
+ *
+ * @warning
+ * This function is not thread-safe; the same file descriptor I/O cannot be
+ * read by another thread at the same time (although it can be written to).
+ *
+ * @note This only works with stream-oriented file descriptors, not with
+ * datagram or packet-oriented ones.
+ *
+ * @return nul-terminated heap-allocated string, or NULL on I/O error.
+ */
 VLC_API char * net_Gets( vlc_object_t *p_this, int fd );
 #define net_Gets(a,b) net_Gets(VLC_OBJECT(a),b)
 
-
 VLC_API ssize_t net_Printf( vlc_object_t *p_this, int fd, const char *psz_fmt, ... ) VLC_FORMAT( 3, 4 );
 #define net_Printf(o,fd,...) net_Printf(VLC_OBJECT(o),fd, __VA_ARGS__)
 VLC_API ssize_t net_vaPrintf( vlc_object_t *p_this, int fd, const char *psz_fmt, va_list args );
diff --git a/src/network/io.c b/src/network/io.c
index 0e36efb6b1..5aa5d65c65 100644
--- a/src/network/io.c
+++ b/src/network/io.c
@@ -224,12 +224,6 @@ int *net_Listen (vlc_object_t *p_this, const char *psz_host,
     return sockv;
 }
 
-/**
- * Reads data from a socket, blocking until all requested data is received or
- * the end of the stream is reached.
- * This function is a cancellation point.
- * @return -1 on error, or the number of bytes of read.
- */
 ssize_t (net_Read)(vlc_object_t *restrict obj, int fd,
                    void *restrict buf, size_t len)
 {
@@ -277,15 +271,6 @@ ssize_t (net_Read)(vlc_object_t *restrict obj, int fd,
     return rd;
 }
 
-/**
- * Writes data to a socket.
- * This blocks until all data is written or an error occurs.
- *
- * This function is a cancellation point.
- *
- * @return the total number of bytes written, or -1 if an error occurs
- * before any data is written.
- */
 ssize_t (net_Write)(vlc_object_t *obj, int fd, const void *buf, size_t len)
 {
     size_t written = 0;
@@ -323,16 +308,6 @@ ssize_t (net_Write)(vlc_object_t *obj, int fd, const void *buf, size_t len)
 }
 
 #undef net_Gets
-/**
- * Reads a line from a file descriptor.
- * This function is not thread-safe; the same file descriptor I/O cannot be
- * read by another thread at the same time (although it can be written to).
- *
- * @note This only works with stream-oriented file descriptors, not with
- * datagram or packet-oriented ones.
- *
- * @return nul-terminated heap-allocated string, or NULL on I/O error.
- */
 char *net_Gets(vlc_object_t *obj, int fd)
 {
     char *buf = NULL;