From 0dcd186b0d188e03da115f5fdc6fc311576e6b76 Mon Sep 17 00:00:00 2001 From: Jonas Devlieghere Date: Tue, 20 Aug 2019 22:20:46 +0000 Subject: [PATCH] [NFC] Fix -Wdocumentation warnings in Utility. This patch fixes a bunch of -Wdocumentation warnings in Utility. I'm sure there are still a bunch outdated comments left, but this fixes the most flagrant inconsistencies that the compiler understands. llvm-svn: 369461 --- lldb/include/lldb/Utility/Args.h | 25 ++++++------ lldb/include/lldb/Utility/DataEncoder.h | 24 ++++++------ lldb/include/lldb/Utility/DataExtractor.h | 48 +++++++++++------------ lldb/include/lldb/Utility/Predicate.h | 10 ++--- lldb/include/lldb/Utility/Status.h | 15 ++----- lldb/include/lldb/Utility/Stream.h | 2 +- lldb/include/lldb/Utility/UUID.h | 17 ++++---- 7 files changed, 61 insertions(+), 80 deletions(-) diff --git a/lldb/include/lldb/Utility/Args.h b/lldb/include/lldb/Utility/Args.h index 6f258498d5ba..2677f2286079 100644 --- a/lldb/include/lldb/Utility/Args.h +++ b/lldb/include/lldb/Utility/Args.h @@ -168,8 +168,8 @@ public: /// Appends a new argument to the end of the list argument list. /// - /// \param[in] arg_cstr - /// The new argument as a NULL terminated C string. + /// \param[in] arg_str + /// The new argument. /// /// \param[in] quote_char /// If the argument was originally quoted, put in the quote char here. @@ -179,30 +179,27 @@ public: void AppendArguments(const char **argv); - /// Insert the argument value at index \a idx to \a arg_cstr. + /// Insert the argument value at index \a idx to \a arg_str. /// /// \param[in] idx /// The index of where to insert the argument. /// - /// \param[in] arg_cstr - /// The new argument as a NULL terminated C string. + /// \param[in] arg_str + /// The new argument. /// /// \param[in] quote_char /// If the argument was originally quoted, put in the quote char here. - /// - /// \return - /// The NULL terminated C string of the copy of \a arg_cstr. void InsertArgumentAtIndex(size_t idx, llvm::StringRef arg_str, char quote_char = '\0'); - /// Replaces the argument value at index \a idx to \a arg_cstr if \a idx is + /// Replaces the argument value at index \a idx to \a arg_str if \a idx is /// a valid argument index. /// /// \param[in] idx /// The index of the argument that will have its value replaced. /// - /// \param[in] arg_cstr - /// The new argument as a NULL terminated C string. + /// \param[in] arg_str + /// The new argument. /// /// \param[in] quote_char /// If the argument was originally quoted, put in the quote char here. @@ -238,12 +235,12 @@ public: /// \see Args::GetArgumentAtIndex (size_t) const void Shift(); - /// Inserts a class owned copy of \a arg_cstr at the beginning of the + /// Inserts a class owned copy of \a arg_str at the beginning of the /// argument vector. /// - /// A copy \a arg_cstr will be made. + /// A copy \a arg_str will be made. /// - /// \param[in] arg_cstr + /// \param[in] arg_str /// The argument to push on the front of the argument stack. /// /// \param[in] quote_char diff --git a/lldb/include/lldb/Utility/DataEncoder.h b/lldb/include/lldb/Utility/DataEncoder.h index 19b7cef9f0ca..7d44afd2ce69 100644 --- a/lldb/include/lldb/Utility/DataEncoder.h +++ b/lldb/include/lldb/Utility/DataEncoder.h @@ -204,12 +204,11 @@ public: /// m_addr_size member variable and should be set correctly prior to /// extracting any address values. /// - /// \param[in,out] offset_ptr - /// A pointer to an offset within the data that will be advanced - /// by the appropriate number of bytes if the value is extracted - /// correctly. If the offset is out of bounds or there are not - /// enough bytes to extract this value, the offset will be left - /// unmodified. + /// \param[in] offset + /// The offset where to encode the address. + /// + /// \param[in] addr + /// The address to encode. /// /// \return /// The next valid offset within data if the put operation @@ -220,19 +219,18 @@ public: /// /// Encodes a C string into the existing data including the terminating /// - /// \param[in,out] offset_ptr - /// A pointer to an offset within the data that will be advanced - /// by the appropriate number of bytes if the value is extracted - /// correctly. If the offset is out of bounds or there are not - /// enough bytes to extract this value, the offset will be left - /// unmodified. + /// \param[in] offset + /// The offset where to encode the string. + /// + /// \param[in] cstr + /// The string to encode. /// /// \return /// A pointer to the C string value in the data. If the offset /// pointed to by \a offset_ptr is out of bounds, or if the /// offset plus the length of the C string is out of bounds, /// NULL will be returned. - uint32_t PutCString(uint32_t offset_ptr, const char *cstr); + uint32_t PutCString(uint32_t offset, const char *cstr); lldb::DataBufferSP &GetSharedDataBuffer() { return m_data_sp; } diff --git a/lldb/include/lldb/Utility/DataExtractor.h b/lldb/include/lldb/Utility/DataExtractor.h index 74174b34ce99..2898c61df333 100644 --- a/lldb/include/lldb/Utility/DataExtractor.h +++ b/lldb/include/lldb/Utility/DataExtractor.h @@ -167,9 +167,8 @@ public: /// the beginning of each line and can be offset by base address \a /// base_addr. \a num_per_line objects will be displayed on each line. /// - /// \param[in] s - /// The stream to dump the output to. If nullptr the output will - /// be dumped to Log(). + /// \param[in] log + /// The log to dump the output to. /// /// \param[in] offset /// The offset into the data at which to start dumping. @@ -362,30 +361,29 @@ public: /// when say copying a partial data value into a register. /// /// \param[in] src_offset - /// The offset into this data from which to start copying an - /// endian entity + /// The offset into this data from which to start copying an endian + /// entity /// /// \param[in] src_len - /// The length of the endian data to copy from this object - /// into the \a dst object + /// The length of the endian data to copy from this object into the \a + /// dst object /// /// \param[out] dst - /// The buffer where to place the endian data. The data might - /// need to be byte swapped (and appropriately padded with - /// zeroes if \a src_len != \a dst_len) if \a dst_byte_order - /// does not match the byte order in this object. + /// The buffer where to place the endian data. The data might need to be + /// byte swapped (and appropriately padded with zeroes if \a src_len != + /// \a dst_len) if \a dst_byte_order does not match the byte order in + /// this object. /// /// \param[in] dst_len - /// The length number of bytes that the endian value will - /// occupy is \a dst. + /// The length number of bytes that the endian value will occupy is \a + /// dst. /// - /// \param[in] byte_order - /// The byte order that the endian value should be in the \a dst - /// buffer. + /// \param[in] dst_byte_order + /// The byte order that the endian value should be in the \a dst buffer. /// /// \return - /// Returns the number of bytes that were copied, or zero if - /// anything goes wrong. + /// Returns the number of bytes that were copied, or zero if anything + /// goes wrong. lldb::offset_t CopyByteOrderedData(lldb::offset_t src_offset, lldb::offset_t src_len, void *dst, lldb::offset_t dst_len, @@ -520,7 +518,7 @@ public: /// enough bytes to extract this value, the offset will be left /// unmodified. /// - /// \param[in] byte_size + /// \param[in] size /// The size in byte of the integer to extract. /// /// \param[in] bitfield_bit_size @@ -558,7 +556,7 @@ public: /// enough bytes to extract this value, the offset will be left /// unmodified. /// - /// \param[in] byte_size + /// \param[in] size /// The size in bytes of the integer to extract. /// /// \param[in] bitfield_bit_size @@ -956,14 +954,14 @@ public: /// unmodified. /// /// \return - // The number of bytes consumed during the extraction. + /// The number of bytes consumed during the extraction. uint32_t Skip_LEB128(lldb::offset_t *offset_ptr) const; /// Test the validity of \a offset. /// /// \return - /// \b true if \a offset is a valid offset into the data in this - /// object, \b false otherwise. + /// true if \a offset is a valid offset into the data in this object, + /// false otherwise. bool ValidOffset(lldb::offset_t offset) const { return offset < GetByteSize(); } @@ -971,8 +969,8 @@ public: /// Test the availability of \a length bytes of data from \a offset. /// /// \return - /// \b true if \a offset is a valid offset and there are \a - /// length bytes available at that offset, \b false otherwise. + /// true if \a offset is a valid offset and there are \a + /// length bytes available at that offset, false otherwise. bool ValidOffsetForDataOfSize(lldb::offset_t offset, lldb::offset_t length) const { return length <= BytesLeft(offset); diff --git a/lldb/include/lldb/Utility/Predicate.h b/lldb/include/lldb/Utility/Predicate.h index f1539b576686..cbccc3e91a8b 100644 --- a/lldb/include/lldb/Utility/Predicate.h +++ b/lldb/include/lldb/Utility/Predicate.h @@ -117,8 +117,7 @@ public: /// How long to wait for the condition to hold. /// /// \return - /// \li m_value if Cond(m_value) is true. - /// \li None otherwise (timeout occurred). + /// m_value if Cond(m_value) is true, None otherwise (timeout occurred). template llvm::Optional WaitFor(C Cond, const Timeout &timeout) { std::unique_lock lock(m_mutex); @@ -151,8 +150,8 @@ public: /// How long to wait for the condition to hold. /// /// \return - /// \li \b true if the \a m_value is equal to \a value - /// \li \b false otherwise (timeout occurred) + /// true if the \a m_value is equal to \a value, false otherwise (timeout + /// occurred). bool WaitForValueEqualTo(T value, const Timeout &timeout = llvm::None) { return WaitFor([&value](T current) { return value == current; }, timeout) != @@ -179,8 +178,7 @@ public: /// How long to wait for the condition to hold. /// /// \return - /// \li m_value if m_value != value - /// \li None otherwise (timeout occurred). + /// m_value if m_value != value, None otherwise (timeout occurred). llvm::Optional WaitForValueNotEqualTo(T value, const Timeout &timeout = llvm::None) { diff --git a/lldb/include/lldb/Utility/Status.h b/lldb/include/lldb/Utility/Status.h index ae730b90dffe..71a9879708a3 100644 --- a/lldb/include/lldb/Utility/Status.h +++ b/lldb/include/lldb/Utility/Status.h @@ -47,8 +47,8 @@ public: /// into ValueType. typedef uint32_t ValueType; - /// Default constructor. - /// + Status(); + /// Initialize the error object with a generic success value. /// /// \param[in] err @@ -56,23 +56,14 @@ public: /// /// \param[in] type /// The type for \a err. - Status(); - explicit Status(ValueType err, lldb::ErrorType type = lldb::eErrorTypeGeneric); - /* implicit */ Status(std::error_code EC); + Status(std::error_code EC); explicit Status(const char *format, ...) __attribute__((format(printf, 2, 3))); - /// Assignment operator. - /// - /// \param[in] err - /// An error code. - /// - /// \return - /// A const reference to this object. const Status &operator=(const Status &rhs); ~Status(); diff --git a/lldb/include/lldb/Utility/Stream.h b/lldb/include/lldb/Utility/Stream.h index b24d4e457177..414f92177303 100644 --- a/lldb/include/lldb/Utility/Stream.h +++ b/lldb/include/lldb/Utility/Stream.h @@ -35,11 +35,11 @@ public: /// Utility class for counting the bytes that were written to a stream in a /// certain time span. + /// /// \example /// ByteDelta delta(*this); /// WriteDataToStream("foo"); /// return *delta; - /// \endcode class ByteDelta { Stream *m_stream; /// Bytes we have written so far when ByteDelta was created. diff --git a/lldb/include/lldb/Utility/UUID.h b/lldb/include/lldb/Utility/UUID.h index dbeb9db611b2..cb2e051a4569 100644 --- a/lldb/include/lldb/Utility/UUID.h +++ b/lldb/include/lldb/Utility/UUID.h @@ -67,10 +67,10 @@ public: std::string GetAsString(llvm::StringRef separator = "-") const; size_t SetFromStringRef(llvm::StringRef str, uint32_t num_uuid_bytes = 16); - - // Same as SetFromStringRef, but if the resultant UUID is all 0 bytes, set the + + // Same as SetFromStringRef, but if the resultant UUID is all 0 bytes, set the // UUID to invalid. - size_t SetFromOptionalStringRef(llvm::StringRef str, + size_t SetFromOptionalStringRef(llvm::StringRef str, uint32_t num_uuid_bytes = 16); // Decode as many UUID bytes (up to 16) as possible from the C string "cstr" @@ -79,14 +79,13 @@ public: /// Decode as many UUID bytes (up to 16) as possible from the C /// string \a cstr. /// - /// \param[in] cstr - /// A NULL terminate C string that points at a UUID string value - /// (no leading spaces). The string must contain only hex - /// characters and optionally can contain the '-' sepearators. + /// \param[in] str + /// An llvm::StringRef that points at a UUID string value (no leading + /// spaces). The string must contain only hex characters and optionally + /// can contain the '-' sepearators. /// /// \param[in] uuid_bytes - /// A buffer of bytes that will contain a full or patially - /// decoded UUID. + /// A buffer of bytes that will contain a full or partially decoded UUID. /// /// \return /// The original string, with all decoded bytes removed.