maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

[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
This commit is contained in:
Jonas Devlieghere 2019-08-20 22:20:46 +00:00
parent 9a95e79b1b
commit 0dcd186b0d
7 changed files with 61 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
lldb/include/lldb/Utility/Args.h
View File

@ -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

24
lldb/include/lldb/Utility/DataEncoder.h
View File

@ -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; }

48
lldb/include/lldb/Utility/DataExtractor.h
View File

@ -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);

10
lldb/include/lldb/Utility/Predicate.h
View File

@ -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) {

15
lldb/include/lldb/Utility/Status.h
View File

@ -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();

2
lldb/include/lldb/Utility/Stream.h
View File

@ -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.

17
lldb/include/lldb/Utility/UUID.h
View File

@ -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.