[Lldb-commits] [lldb] r369461 - [NFC] Fix -Wdocumentation warnings in Utility.
Jonas Devlieghere via lldb-commits
lldb-commits at lists.llvm.org
Tue Aug 20 15:20:47 PDT 2019
Author: jdevlieghere
Date: Tue Aug 20 15:20:46 2019
New Revision: 369461
URL: http://llvm.org/viewvc/llvm-project?rev=369461&view=rev
Log:
[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.
Modified:
lldb/trunk/include/lldb/Utility/Args.h
lldb/trunk/include/lldb/Utility/DataEncoder.h
lldb/trunk/include/lldb/Utility/DataExtractor.h
lldb/trunk/include/lldb/Utility/Predicate.h
lldb/trunk/include/lldb/Utility/Status.h
lldb/trunk/include/lldb/Utility/Stream.h
lldb/trunk/include/lldb/Utility/UUID.h
Modified: lldb/trunk/include/lldb/Utility/Args.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/Utility/Args.h?rev=369461&r1=369460&r2=369461&view=diff
==============================================================================
--- lldb/trunk/include/lldb/Utility/Args.h (original)
+++ lldb/trunk/include/lldb/Utility/Args.h Tue Aug 20 15:20:46 2019
@@ -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
Modified: lldb/trunk/include/lldb/Utility/DataEncoder.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/Utility/DataEncoder.h?rev=369461&r1=369460&r2=369461&view=diff
==============================================================================
--- lldb/trunk/include/lldb/Utility/DataEncoder.h (original)
+++ lldb/trunk/include/lldb/Utility/DataEncoder.h Tue Aug 20 15:20:46 2019
@@ -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; }
Modified: lldb/trunk/include/lldb/Utility/DataExtractor.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/Utility/DataExtractor.h?rev=369461&r1=369460&r2=369461&view=diff
==============================================================================
--- lldb/trunk/include/lldb/Utility/DataExtractor.h (original)
+++ lldb/trunk/include/lldb/Utility/DataExtractor.h Tue Aug 20 15:20:46 2019
@@ -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);
Modified: lldb/trunk/include/lldb/Utility/Predicate.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/Utility/Predicate.h?rev=369461&r1=369460&r2=369461&view=diff
==============================================================================
--- lldb/trunk/include/lldb/Utility/Predicate.h (original)
+++ lldb/trunk/include/lldb/Utility/Predicate.h Tue Aug 20 15:20:46 2019
@@ -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 <typename C>
llvm::Optional<T> WaitFor(C Cond, const Timeout<std::micro> &timeout) {
std::unique_lock<std::mutex> 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<std::micro> &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<T>
WaitForValueNotEqualTo(T value,
const Timeout<std::micro> &timeout = llvm::None) {
Modified: lldb/trunk/include/lldb/Utility/Status.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/Utility/Status.h?rev=369461&r1=369460&r2=369461&view=diff
==============================================================================
--- lldb/trunk/include/lldb/Utility/Status.h (original)
+++ lldb/trunk/include/lldb/Utility/Status.h Tue Aug 20 15:20:46 2019
@@ -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();
Modified: lldb/trunk/include/lldb/Utility/Stream.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/Utility/Stream.h?rev=369461&r1=369460&r2=369461&view=diff
==============================================================================
--- lldb/trunk/include/lldb/Utility/Stream.h (original)
+++ lldb/trunk/include/lldb/Utility/Stream.h Tue Aug 20 15:20:46 2019
@@ -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.
Modified: lldb/trunk/include/lldb/Utility/UUID.h
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/include/lldb/Utility/UUID.h?rev=369461&r1=369460&r2=369461&view=diff
==============================================================================
--- lldb/trunk/include/lldb/Utility/UUID.h (original)
+++ lldb/trunk/include/lldb/Utility/UUID.h Tue Aug 20 15:20:46 2019
@@ -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.
More information about the lldb-commits
mailing list