diff options
author | Daniel Boles <dboles@src.gnome.org> | 2018-12-16 21:46:55 +0000 |
---|---|---|
committer | Daniel Boles <dboles.src@gmail.com> | 2018-12-16 22:01:51 +0000 |
commit | ecf5aa94e2c057ac82d64355a48fc0efdc346573 (patch) | |
tree | 79e82c42d471ee5cf60abb3c476d7fe86f7b54b2 | |
parent | 93666c1663d54dd8c1ee60eba6f69405ed002560 (diff) | |
download | glibmm-ecf5aa94e2c057ac82d64355a48fc0efdc346573.tar.gz |
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 https://gitlab.gnome.org/GNOME/gtkmm/merge_requests/9 for more
disussion on the rationale for this.
-rw-r--r-- | glib/src/fileutils.hg | 4 | ||||
-rw-r--r-- | glib/src/iochannel.hg | 12 |
2 files changed, 8 insertions, 8 deletions
diff --git a/glib/src/fileutils.hg b/glib/src/fileutils.hg index 3abb38b2..c6e73ede 100644 --- a/glib/src/fileutils.hg +++ b/glib/src/fileutils.hg @@ -355,8 +355,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>. @@ -370,7 +370,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>. diff --git a/glib/src/iochannel.hg b/glib/src/iochannel.hg index 5df0ebc5..00e49e36 100644 --- a/glib/src/iochannel.hg +++ b/glib/src/iochannel.hg @@ -158,7 +158,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 @@ -170,7 +170,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. @@ -181,8 +181,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 @@ -192,7 +192,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 @@ -201,7 +201,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::IO_STATUS_NORMAL on success. This function never * returns Glib::IO_STATUS_EOF. * @throw Glib::IOChannelError @@ -224,7 +224,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 |