mesos git commit: Doxygen-ification of comments in libprocess io.hpp.

[be...@apache.org]

Repository: mesos
Updated Branches:
  refs/heads/master 940f52548 -> 69b8ae501


Doxygen-ification of comments in libprocess io.hpp.

Review: https://reviews.apache.org/r/36279


Project: http://git-wip-us.apache.org/repos/asf/mesos/repo
Commit: http://git-wip-us.apache.org/repos/asf/mesos/commit/69b8ae50
Tree: http://git-wip-us.apache.org/repos/asf/mesos/tree/69b8ae50
Diff: http://git-wip-us.apache.org/repos/asf/mesos/diff/69b8ae50

Branch: refs/heads/master
Commit: 69b8ae5012294c0339cb0fe19d2902b3d370cfa9
Parents: 940f525
Author: Joseph Wu <jo...@mesosphere.io>
Authored: Tue Jul 21 21:56:13 2015 -0700
Committer: Benjamin Hindman <be...@gmail.com>
Committed: Tue Jul 21 21:56:14 2015 -0700

----------------------------------------------------------------------
 3rdparty/libprocess/include/process/io.hpp | 115 +++++++++++++++---------
 1 file changed, 75 insertions(+), 40 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/mesos/blob/69b8ae50/3rdparty/libprocess/include/process/io.hpp
----------------------------------------------------------------------
diff --git a/3rdparty/libprocess/include/process/io.hpp b/3rdparty/libprocess/include/process/io.hpp
index 2457163..975923f 100644
--- a/3rdparty/libprocess/include/process/io.hpp
+++ b/3rdparty/libprocess/include/process/io.hpp
@@ -25,66 +25,101 @@
 namespace process {
 namespace io {
 
-// Possible events for polling.
+/**
+ * A possible event while polling.
+ *
+ * @see process::io::poll
+ */
 const short READ = 0x01;
+
+/**
+ * @copydoc process::io::READ
+ */
 const short WRITE = 0x02;
 
-// Buffered read chunk size. Roughly 16 pages.
+/**
+ * Buffered read chunk size.
+ *
+ * Roughly 16 pages.
+ */
 const size_t BUFFERED_READ_SIZE = 16*4096;
 
+/**
+ * Returns the events (a subset of the events specified) that can be
+ * performed on the specified file descriptor without blocking.
+ *
+ * @see process::io::READ
+ * @see process::io::WRITE
+ */
 // TODO(benh): Add a version which takes multiple file descriptors.
-// Returns the events (a subset of the events specified) that can be
-// performed on the specified file descriptor without blocking.
 Future<short> poll(int fd, short events);
 
 
-// Performs a single non-blocking read by polling on the specified
-// file descriptor until any data can be be read. The future will
-// become ready when some data is read (may be less than that
-// specified by size). A failure will be returned if an error is
-// detected. If end-of-file is reached, value zero will be
-// returned. Note that the return type of this function differs from
-// the standard 'read'. In particular, this function returns the
-// number of bytes read or zero on end-of-file (an error is indicated
-// by failing the future, thus only a 'size_t' is necessary rather
-// than a 'ssize_t').
+/**
+ * Performs a single non-blocking read by polling on the specified
+ * file descriptor until any data can be be read.
+ *
+ * The future will become ready when some data is read (may be less than
+ * the specified size).
+ *
+ * @return The number of bytes read or zero on EOF.
+ *     A failure will be returned if an error is detected.
+ */
 Future<size_t> read(int fd, void* data, size_t size);
 
 
-// Performs a series of asynchronous reads, until EOF is reached.
-// NOTE: When using this, ensure the sender will close the connection
-// so that EOF can be reached.
-//
-// NOTE: the specified file descriptor is duplicated and set to
-// close-on-exec and made non-blocking (which will return a failure if
-// these operations can not be performed).
+/**
+ * Performs a series of asynchronous reads, until EOF is reached.
+ *
+ * **NOTE**: when using this, ensure the sender will close the connection
+ * so that EOF can be reached.
+ *
+ * @return The concatentated result of the reads.
+ *     A failure will be returned if the file descriptor is bad, or if the
+ *     file descriptor cannot be duplicated, set to close-on-exec,
+ *     or made non-blocking.
+ */
 Future<std::string> read(int fd);
 
 
-// Performs a non-blocking write by polling on the specified file
-// descriptor until data can be be written. The future will become
-// ready when some data is written with the number of bytes that were
-// written. This may be less than the specified size of the data. A
-// failure will be returned if an error is detected. In the special
-// case of writing to a socket or pipe, an error will be returned if
-// the read end of the socket or pipe has been closed.
+/**
+ * Performs a single non-blocking write by polling on the specified
+ * file descriptor until data can be be written.
+ *
+ * The future will become ready when some data is written (may be less than
+ * the specified size of the data).
+ *
+ * @return The number of bytes written.
+ *     A failure will be returned if an error is detected.
+ *     If writing to a socket or pipe, an error will be returned if the
+ *     the read end of the socket or pipe has been closed.
+ */
 Future<size_t> write(int fd, void* data, size_t size);
 
 
-// Performs a series of asynchronous writes until all of data has been
-// written or an error occured in which case a failure is returned.
-//
-// NOTE: the specified file descriptor is duplicated and set to
-// close-on-exec and made non-blocking (which will return a failure if
-// these operations can not be performed).
+/**
+ * Performs a series of asynchronous writes, until all of data has been
+ * written.
+ *
+ * @return Nothing or a failure if an error occured.
+ *     A failure will be returned if the file descriptor is bad, or if the
+ *     file descriptor cannot be duplicated, set to close-on-exec,
+ *     or made non-blocking.
+ */
 Future<Nothing> write(int fd, const std::string& data);
 
-
-// Redirect output from 'from' file descriptor to 'to' file descriptor
-// or /dev/null if 'to' is None. Note that depending on how we
-// redirect output we duplicate the 'from' and 'to' file descriptors
-// so we can control their lifetimes. Returns after EOF has been hit
-// on 'from' or some form of failure has occured.
+/**
+ * Redirect output from the 'from' file descriptor to the 'to' file
+ * descriptor (or /dev/null if 'to' is None).
+ *
+ * The 'to' and 'from' file descriptors will be duplicated so that the
+ * file descriptors' lifetimes can be controlled within this function.
+ *
+ * @return Nothing after EOF has been encountered on 'from' or if a
+ *     failure has occurred. A failure will be returned if the file
+ *     descriptor is bad, or if the file descriptor cannot be duplicated,
+ *     set to close-on-exec, or made non-blocking.
+ */
 Future<Nothing> redirect(int from, Option<int> to, size_t chunk = 4096);
 
 } // namespace io {