Commit 563913e1 authored by Daniel Boles's avatar Daniel Boles

fileutils|IOChannel: Don’t use @retval on out args

as it is for documenting particular values of the return variable.

Replace @retval with @param[out], and while here, reorder some arguments
in doc comments to match the order they have in function argument lists.

See gtkmm!9 for more
disussion on the rationale for this.
parent b256e44a
......@@ -288,8 +288,8 @@ int mkstemp(std::string& filename_template);
*
* The actual name used is returned in @a name_used.
*
* @param[out] name_used The actual name used.
* @param prefix Template for file name, basename only.
* @retval name_used The actual name used.
* @return A file handle (as from <tt>open()</tt>) to the file opened for reading
* and writing. The file is opened in binary mode on platforms where there is a
* difference. The file handle should be closed with <tt>close()</tt>.
......@@ -303,7 +303,7 @@ int file_open_tmp(std::string& name_used, const std::string& prefix);
* This function works like file_open_tmp(std::string&, const std::string&)
* but uses a default basename prefix.
*
* @retval name_used The actual name used.
* @param[out] name_used The actual name used.
* @return A file handle (as from <tt>open()</tt>) to the file opened for reading
* and writing. The file is opened in binary mode on platforms where there is a
* difference. The file handle should be closed with <tt>close()</tt>.
......
......@@ -168,7 +168,7 @@ public:
#endif /* G_OS_WIN32 */
/** Read a single UCS-4 character.
* @retval thechar The Unicode character.
* @param[out] thechar The Unicode character.
* @return The status of the operation.
* @throw Glib::IOChannelError
* @throw Glib::ConvertError
......@@ -180,7 +180,7 @@ public:
* @param count The size of the buffer in bytes. Note that the buffer may
* not be complelely filled even if there is data in the buffer if the
* remaining data is not a complete character.
* @retval bytes_read The number of bytes read. This may be zero even on
* @param[out] bytes_read The number of bytes read. This may be zero even on
* success if @a count < 6 and the channel's encoding is not <tt>""</tt>.
* This indicates that the next UTF-8 character is too wide for the buffer.
* @return The status of the operation.
......@@ -191,8 +191,8 @@ public:
g_io_channel_read_chars, errthrow)
/** Read a maximum of @a count bytes into @a str.
* @param[out] str The characters that have been read.
* @param count The maximum number of bytes to read.
* @retval str The characters that have been read.
* @return The status of the operation.
* @throw Glib::IOChannelError
* @throw Glib::ConvertError
......@@ -202,7 +202,7 @@ public:
/** Read a whole line.
* Reads until the line separator is found, which is included
* in the result string.
* @retval line The line that was read.
* @param[out] line The line that was read.
* @return The status of the operation.
* @throw Glib::IOChannelError
* @throw Glib::ConvertError
......@@ -211,7 +211,7 @@ public:
_IGNORE(g_io_channel_read_line, g_io_channel_read_line_string)
/** Reads all the remaining data from the file.
* @retval str The resulting string.
* @param[out] str The resulting string.
* @return Glib::IOStatus::NORMAL on success. This function never
* returns Glib::IOStatus::ENDOFFILE.
* @throw Glib::IOChannelError
......@@ -234,7 +234,7 @@ public:
/** Write a memory area of @a count bytes to the I/O channel.
* @param buf The start of the memory area.
* @param count The number of bytes to write.
* @retval bytes_written The number of bytes written to the channel.
* @param[out] bytes_written The number of bytes written to the channel.
* @return The status of the operation.
* @throw Glib::IOChannelError
* @throw Glib::ConvertError
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment