diff --git a/base/include/parcel.h b/base/include/parcel.h
index 3ce1b4d8ea82c67e1b326cd90cf39cace5700b56..89ac76c3ad181a228d57f56bce7f749febe76b3c 100644
--- a/base/include/parcel.h
+++ b/base/include/parcel.h
@@ -16,9 +16,10 @@
/**
* @file parcel.h
*
- * @brief Provide classes for data container implemented in c_utils.
+ * @brief Provides classes for the data container implemented in c_utils.
*
- * Including class Parcel, Parcelable and related memory Allocator.
+ * The Parcel and Parcelable classes and the related memory
+ * allocator are provided.
*/
#ifndef OHOS_UTILS_PARCEL_H
@@ -35,10 +36,10 @@ namespace OHOS {
class Parcel;
/**
- * @brief Interface for class whose Instance can be written into a Parcel.
+ * @brief Defines a class for which the instance can be written into a parcel.
*
- * @note If this object is remote, its position intends to
- * use in kernel data transaction.
+ * @note If this object is remote, its position will be used in
+ * kernel data transaction.
*/
class Parcelable : public virtual RefBase {
public:
@@ -46,39 +47,41 @@ public:
Parcelable();
/**
- * @brief Construct a new Parcelable object.
+ * @brief Creates a `Parcelable` object.
*
- * @param asRemote Specifies whether this object is remote.
+ * @param asRemote Specifies whether the object is remote.
*/
explicit Parcelable(bool asRemote);
/**
- * @brief Write a parcelable object to the given parcel.
+ * @brief Writes a `Parcelable` object into a parcel.
*
- * @param parcel Target parcel to write to.
- * @return Return true being written on success or false if any error occur.
- * @note If this object is remote, its position will be saved in the parcel.
- * @note A static Unmarshalling function must also be implemented, so that
- * you can get data from the given parcel into this parcelable object.
+ * @param parcel Indicates the parcel.
+ * @return Returns `true` if the operation is successful; returns `false`
+ * otherwise.
+ * @note If the `Parcelable` object is remote, its position will be saved
+ * in the parcel.
+ * @note You must implement a static Unmarshalling function to
+ * fetch data from the given parcel into this `Parcelable` object.
* See `static TestParcelable *Unmarshalling(Parcel &parcel)` as an example.
*/
virtual bool Marshalling(Parcel &parcel) const = 0;
/**
- * @brief Enum flag to describe behaviors of the Parcelable object.
+ * @brief Enumerates the behavior types of a `Parcelable` object.
*
- * @var IPC Indicate the object can be used in IPC.
- * @var RPC Indicate the object can be used in RPC.
- * @var HOLD_OBJECT Indicate the object will ensure
- * alive during data transaction.
+ * @var IPC Indicate an object that can be used in IPC.
+ * @var RPC Indicate an object that can be used in RPC.
+ * @var HOLD_OBJECT Indicate an object that will be always alive
+ * during data transaction.
*
*/
enum BehaviorFlag { IPC = 0x01, RPC = 0x02, HOLD_OBJECT = 0x10 };
/**
- * @brief Enable specified behavior.
+ * @brief Enables the specified behavior.
*
- * @param b Specific flag value.
+ * @param b Indicates the behavior.
* @see BehaviorFlag.
*/
inline void SetBehavior(BehaviorFlag b) const
@@ -87,9 +90,10 @@ public:
}
/**
- * @brief Disable specified behavior.
+ * @brief Disables the specified behavior.
*
- * @param b Specific flag value. See BehaviorFlag.
+ * @param b Indicates the behavior.
+ * @see BehaviorFlag.
*/
inline void ClearBehavior(BehaviorFlag b) const
{
@@ -97,9 +101,12 @@ public:
}
/**
- * @brief Check whether specified behavior is enabled.
+ * @brief Checks whether the specified behavior is enabled.
*
- * @param b Specific flag value.
+ * @param b Indicates the behavior.
+
+ * @return Returns `true` if the behavior is enabled; returns `false`
+ * otherwise.
* @see BehaviorFlag.
*/
inline bool TestBehavior(BehaviorFlag b) const
@@ -108,12 +115,12 @@ public:
}
public:
- bool asRemote_; // if the object is remote
- mutable uint8_t behavior_; // value of flag of behaviors
+ bool asRemote_; // If the object is remote.
+ mutable uint8_t behavior_; // Behavior of the object.
};
/**
- * @brief Interface for memory allocator of the data in Parcel.
+ * @brief Defines a memory allocator for data in `Parcel`.
*/
class Allocator {
public:
@@ -127,144 +134,150 @@ public:
};
/**
- * @brief Default implement of Allocator.
+ * @brief Provides the default implementation for a memory allocator.
*
- * @note Allocator defined by user for a parcel need be specified manually.
+ * @note A non-default allocator for a parcel must be specified manually.
*/
class DefaultAllocator : public Allocator {
public:
/**
- * @brief Use `malloc()` to allocate memory for a parcel.
+ * @brief Allocates memory for this parcel.
*
- * @param size Size of desired memory region.
- * @return Void-type pointer to the memory region.
+ * @param size Indicates the size of the memory to allocate.
+ * @return Returns the void pointer to the memory region.
*/
void *Alloc(size_t size) override;
/**
- * @brief Use `free()` to deallocate memory for a parcel.
+ * @brief Deallocates memory for this parcel.
*
- * @param data Void-type pointer to the memory region.
+ * @param data Indicates the void pointer to the memory region.
*/
void Dealloc(void *data) override;
private:
/**
- * @brief Use `realloc()` to reallocate memory for a parcel.
+ * @brief Reallocates memory for this parcel.
*
- * @param data Void-type pointer to the existed memory region.
- * @param newSize New desired size of memory region.
- * @return Void-type pointer to the new memory region.
+ * @param data Indicates the void pointer to the existing memory region.
+ * @param newSize Indicates the size of the memory to reallocate.
+ * @return Returns the void pointer to the new memory region.
*/
void *Realloc(void *data, size_t newSize) override;
};
/**
- * @brief A data/message container.
+ * @brief Provides a data/message container.
*
- * Contains interfaces for writing and reading data of various types,
- * including primitives, Parcelable objects etc.
+ * This class provides methods for writing and reading data of various types,
+ * including primitives and parcelable objects.
*
- * @note Usually used in IPC, RPC.
+ * @note This class is usually used in IPC and RPC scenarios.
*/
class Parcel {
public:
Parcel();
/**
- * @brief Construct a new Parcel object with specified Allocator.
+ * @brief Creates a `Parcel` object with the specified memory allocator.
*
- * @param allocator Specified Allocator.
+ * @param allocator Indicates the memory allocator.
*/
explicit Parcel(Allocator *allocator);
virtual ~Parcel();
/**
- * @brief Get total size of existed data in this parcel.
+ * @brief Obtains the total size of existing data in this parcel.
*
- * @return Value of the size in bytes.
+ * @return Returns the size, in bytes.
*/
size_t GetDataSize() const;
/**
- * @brief Get the pointer to the beginning of data in this parcel.
+ * @brief Obtains the pointer to the beginning of data in this parcel.
*
- * @return `uintptr_t`-type pointer.
+ * @return Returns a pointer of the `uintptr_t` type.
*/
uintptr_t GetData() const;
/**
- * @brief Get position of every object written in this parcel.
+ * @brief Obtains the position (offset) of every object written
+ * in this parcel.
*
- * @return `binder_size_t`-type pointer to
+ * @return Returns a pointer of the `binder_size_t` type to
* the first slot of the position array.
* @see flat_obj.h
*/
binder_size_t GetObjectOffsets() const;
/**
- * @brief Get total size of all of the current positions.
+ * @brief Obtains the size of the position array.
*
- * @return Value of the size in bytes.
+ * @return Returns the size, in bytes.
*/
size_t GetOffsetsSize() const;
/**
- * @brief Get total availiable bytes to write to this parcel.
+ * @brief Obtains the total number of available bytes to write
+ * into this parcel.
*
- * @return Amount of the availiable bytes.
+ * @return Returns the number of available bytes.
*/
size_t GetWritableBytes() const;
/**
- * @brief Get total availiable bytes to read from this parcel.
+ * @brief Obtains the total number of available bytes to read
+ * from this parcel.
*
- * @return Amount of the availiable bytes.
+ * @return Returns the number of available bytes.
*/
size_t GetReadableBytes() const;
/**
- * @brief Get total capacity of this parcel,
- * i.e. size of current data region in parcel.
+ * @brief Obtains the total capacity of this parcel, that is, the size of
+ * the current data region in the parcel.
*
- * @return Value of the capacity in bytes.
+ * @return Returns the capacity, in bytes.
*/
size_t GetDataCapacity() const;
/**
- * @brief Get maximum capacity of this parcel.
+ * @brief Obtains the maximum capacity of this parcel.
*
- * @return Value of the capacity in bytes.
+ * @return Returns the capacity, in bytes.
*/
size_t GetMaxCapacity() const;
/**
- * @brief Set capacity of this parcel,
- * i.e. size of current data region in parcel.
+ * @brief Sets the capacity for this parcel, that is, the size of the
+ * current data region in the parcel.
*
- * @param newCapacity Desired new capacity.
- * @return Return True on success, or false if any error occur.
- * @note Corresponding Allocator will try to reallocate
- * the data region with new capacity.
+ * @param newCapacity Indicates the capacity to set.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
+ * @note The memory allocator will try to reallocate the data region
+ * with the new capacity.
*
*/
bool SetDataCapacity(size_t newCapacity);
/**
- * @brief Set total size of existed data in this parcel.
+ * @brief Sets the total size of existing data in this parcel.
*
- * @param dataSize Desired value of size in bytes.
- * @return Return True on success, or false if any error occur.
- * @note Avoid using it independently, otherwise it may not
- * represents the correct size of existed data.
+ * @param dataSize Indicates the size, in bytes.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
+ * @note Do not call this function independently; otherwise, it may fail to
+ * return the correct data size.
*/
bool SetDataSize(size_t dataSize);
/**
- * @brief Set maximux capacity of this parcel.
+ * @brief Sets the maximum capacity for this parcel.
*
- * @param maxCapacity Desired value of maximum capacity.
- * @return Return True on success, or false if any error occur.
+ * @param maxCapacity Indicates the maximum capacity to set.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool SetMaxCapacity(size_t maxCapacity);
@@ -283,150 +296,166 @@ public:
bool WritePointer(uintptr_t value);
/**
- * @brief Write a data region(buffer) to this parcel.
+ * @brief Writes a data region (buffer) to this parcel.
*
- * @param data Void-type pointer to the buffer.
- * @param size Size of the buffer to be written.
- * @return Return True on success, or false if any error occur.
+ * @param data Indicates the void pointer to the buffer.
+ * @param size Indicates the size of the buffer.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool WriteBuffer(const void *data, size_t size);
/**
- * @brief Write a data region(buffer) to this parcel
- * in alignment and with terminator replaced.
+ * @brief Writes a data region (buffer) to this parcel in alignment
+ * and with the terminator replaced.
*
- * @param data Void-type pointer to the buffer.
- * @param size Size of the buffer to be written.
- * @param typeSize Size of the terminator.
- * @return Return True on success, or false if any error occur.
+ * @param data Indicates the void pointer to the buffer.
+ * @param size Indicates the size of the buffer.
+ * @param typeSize Indicates the size of the terminator.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
* @note The last several bytes specified by `typeSize` of the aligned data
- * will be deemed as a terminator, and then will be replaced by
- * '0b00000000'.
+ * will be treated as a terminator and replaced by '0b00000000'.
*/
bool WriteBufferAddTerminator(const void *data, size_t size, size_t typeSize);
/**
- * @brief Write a data region(buffer) to this parcel without padding.
+ * @brief Writes a data region (buffer) to this parcel.
*
- * @param data Void-type pointer to the buffer.
- * @param size Size of the buffer to be written.
- * @return Return True on success, or false if any error occur.
+ * Currently, this function provides the same capability as `WriteBuffer()`.
+ *
+ * @param data Indicates the void pointer to the buffer.
+ * @param size Indicates the size of the buffer.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool WriteUnpadBuffer(const void *data, size_t size);
/**
- * @brief Write a C-style string to this parcel.
+ * @brief Writes a C-style string to this parcel.
*
- * Default terminator `\0` of C-style string will also write.
+ * The default terminator `\0` of the C-style string will also be written.
*
- * @param value A C-style string, i.e. char-type pointer.
- * @return Return True on success, or false if any error occur.
+ * @param value Indicates a pointer of the char type to a C-style string.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool WriteCString(const char *value);
/**
- * @brief Write a C++ string(`std::u16string`) to this parcel.
+ * @brief Writes a C++ string (`std::string`) to this parcel.
*
- * The exact length of the string will write first, then the string itself
- * with an appended terminator `\0` will write.
+ * The exact length of the string will be written first, and then the string
+ * itself with the appended terminator `\0` will be written.
*
- * @param value An `std::string` object passed by reference.
- * @return Return True on success, or false if any error occur.
+ * @param value Indicates the reference to an `std::string` object.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool WriteString(const std::string &value);
/**
- * @brief Write a C++ UTF-16 encoded string(`std::string`) to this parcel.
+ * @brief Writes a C++ UTF-16 encoded string (`std::u16string`)
+ * to this parcel.
*
- * The exact length of the string will write first, then the string itself
- * with an appended terminator `\0` will write.
+ * The exact length of the string will be written first, and then the string
+ * itself with the appended terminator `\0` will be written.
*
- * @param value An `std::u16string` object passed by reference.
- * @return Return True on success, or false if any error occur.
+ * @param value Indicates the reference to an `std::u16string` object.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool WriteString16(const std::u16string &value);
/**
- * @brief Write a UTF-16 encoded string
- * with specified length to this parcel.
+ * @brief Writes a UTF-16 encoded string with the specified length
+ * to this parcel.
*
- * An `std::u16string` object will be constructed by input `char16_t*`
+ * An `std::u16string` object will be constructed based on the `char16_t*`
* pointer and the length `len` first. Then the input length and the string
- * data in `u16string` object with an appended terminator `\0` will write.
+ * data in the `u16string` object with the appended terminator `\0` will
+ * be written.
*
- * @param value Pointer to the UTF-16 encoded string.
- * @param len Exact length of the input string.
- * @return Return True on success, or false if any error occur.
+ * @param value Indicates the pointer to a UTF-16 encoded string.
+ * @param len Indicates the exact length of the input string.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool WriteString16WithLength(const char16_t *value, size_t len);
/**
- * @brief Write a UTF-8 encoded string
- * with specified length to this parcel.
+ * @brief Writes a UTF-8 encoded string with the specified length
+ * to this parcel.
*
- * The input length `len` and the string data
- * with an appended terminator `\0` will write.
+ * The input length `len` and the string itself
+ * with the appended terminator `\0` will be written.
*
- * @param value Pointer to the UTF-8 encoded string.
- * @param len Exact length of the input string.
- * @return Return True on success, or false if any error occur.
+ * @param value Indicates the pointer to a UTF-8 encoded string.
+ * @param len Indicates the exact length of the input string.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool WriteString8WithLength(const char *value, size_t len);
/**
- * @brief Write a Parcelable object to this parcel.
+ * @brief Writes a `Parcelable` object to this parcel.
*
- * Remote object will be written by `WriteRemoteObject(const Parcelable *)`.
- * Non-remote object will be written by its own
- * `Marshalling(Parcel &parcel)`.
+ * Call `WriteRemoteObject(const Parcelable *)` to write a remote object.
+ * Call `Marshalling(Parcel &parcel)` to write a non-remote object.
*
- * @param object Pointer to the input Parcelable object.
- * @return Return True on success, or false if any error occur.
- * @note '0' of `Int32_t` will write if input pointer is `nullptr`.
+ * @param object Indicates the pointer to a `Parcelable` object.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
+ * @note The value '0' of `Int32_t` will be written if a null pointer
+ * is passed in.
*/
bool WriteParcelable(const Parcelable *object);
/**
- * @brief Write a Parcelable object to this parcel,
- * and enable its behavior of `HOLD_OBJECT`.
+ * @brief Writes a `Parcelable` object to this parcel, and enables its
+ * behavior of `HOLD_OBJECT`.
*
- * @param object Smart pointer to the input parcelable object.
- * @return Return True on success, or false if any error occur.
+ * @param object Indicates the smart pointer to a `Parcelable` object.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool WriteStrongParcelable(const sptr &object);
/**
- * @brief Write a remote object to this parcel.
+ * @brief Writes a remote object to this parcel.
*
- * @param object Pointer to a remote object.
- * @return Return True on success, or false if any error occur.
- * @note If `HOLD_OBJECT` is enabled for the input object, it will stay
+ * @param object Indicates the pointer to a remote object.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
+ * @note If `HOLD_OBJECT` is enabled for the remote object, it will stay
* alive as long as this parcel is alive.
*
*/
bool WriteRemoteObject(const Parcelable *object);
/**
- * @brief Write an object to this parcel.
+ * @brief Writes an object to this parcel.
*
- * Use its own `Marshalling(Parcel &parcel)` when `nullptr` as input,
- * otherwise use `WriteRemoteObject(const Parcelable *)`.
+ * Use its own `Marshalling(Parcel &parcel)` when a null pointer is passed
+ * in; in other scenarios, use `WriteRemoteObject(const Parcelable *)`.
*
- * @tparam T Specific class type of the input object.
- * @param object Smart pointer to the input object.
- * @return Return True on success, or false if any error occur.
+ * @tparam T Indicates the class type of the object.
+ * @param object Indicates the smart pointer to the object.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
template
bool WriteObject(const sptr &object);
/**
- * @brief Parse input data by this parcel.
+ * @brief Parses input data by this parcel.
*
- * @param data Pointer to input data.
- * @param size Size of input data(Bytes).
- * @return Return True on success, or false if any error occur.
- * @note Only read operation from this parcel is permitted after successful
- * calling this method.
+ * @param data Indicates the pointer to input data.
+ * @param size Indicates the size of the input data, in bytes.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
+ * @note Only the read operation from this parcel is allowed after
+ * successful calling of this method.
*/
bool ParseFrom(uintptr_t data, size_t size);
@@ -477,200 +506,212 @@ public:
bool ReadDouble(double &value);
/**
- * @brief Read a block of data(buffer data) from this parcel.
+ * @brief Reads a block of data (buffer data) from this parcel.
*
- * @param length Size of the buffer(Bytes).
- * @return A `uint8_t` pointer to the buffer.
+ * @param length Indicates the size of the buffer, in bytes.
+ * @return Returns a pointer of the `uint8_t` type to the buffer.
*/
const uint8_t *ReadBuffer(size_t length);
/**
- * @brief Read a block of data(buffer data) without padding(alignment) from
- * this parcel.
+ * @brief Reads a block of data (buffer data) without padding (alignment)
+ * from this parcel.
*
- * This method will read the effective data whose length specified by
- * `length` and discard bytes for padding.
+ * This method will read the effective data with the specified
+ * `length` and discard the bytes used for padding.
*
- * @param length Effective size of the buffer(Bytes).
- * @return A `uint8_t` pointer to the buffer.
+ * @param length Indicates the effective size of the buffer, in bytes.
+ * @return Returns a pointer of the `uint8_t` type to the buffer.
*
*/
const uint8_t *ReadUnpadBuffer(size_t length);
/**
- * @brief Skip the next several bytes specifed by `bytes` in read process.
+ * @brief Skips the next several bytes specified by `bytes` in the read
+ * operation.
*
- * @param bytes Skipped number of bytes.
+ * @param bytes Indicates the number of bytes to skip.
*/
void SkipBytes(size_t bytes);
/**
- * @brief Read a C-style string from this parcel.
+ * @brief Reads a C-style string from this parcel.
*
- * @return A C-style string, which is represented by a `char`-type pointer.
+ * @return Returns a pointer of the `char` type to the C-style string.
*/
const char *ReadCString();
/**
- * @brief Read a C++ string(`std::string`) object from this parcel.
+ * @brief Reads a C++ string (`std::string`) object from this parcel.
*
- * @return An `std::string` object.
+ * @return Returns a pointer of the `std::string` type to the C-style
+ * string.
*/
const std::string ReadString();
/**
- * @brief Read a C++ string(`std::string`) object from this parcel to input
- * object.
+ * @brief Reads a C++ string (`std::string`) object from this parcel to
+ * an object.
*
- * @param value Target receiver `std::string` object.
- * @return Return True on success, or false if any error occur.
+ * @param value Indicates the `std::string` object to hold the data read.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool ReadString(std::string &value);
/**
- * @brief Read a C++ UTF-16 encoded string(`std::string`) object from this
- * parcel.
+ * @brief Reads a C++ UTF-16 encoded string (`std::u16string`) object
+ * from this parcel.
*
- * @return An `std::u16string` object.
+ * @return Returns a pointer of the `std::u16string` type to the C-style
+ * string.
*/
const std::u16string ReadString16();
/**
- * @brief Read a C++ UTF-16 string(`std::u16string`) object from this
- * parcel to input object.
+ * @brief Reads a C++ UTF-16 string (`std::u16string`) object from this
+ * parcel to an object.
*
- * @param value Target receiver `std::string` object.
- * @return Return True on success, or false if any error occur.
+ * @param value Indicates the `std::u16string` object to hold the data read.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool ReadString16(std::u16string &value);
/**
- * @brief Read a C++ UTF-16 string(`std::u16string`) object and its length
+ * @brief Reads a C++ UTF-16 string (`std::u16string`) object and its length
* from this parcel.
*
- * @param len `int32_t`-type variable passed by reference to receive the
- * length.
- * @return An output `std::u16string` object.
+ * @param len Indicates the reference to a variable of the `int32_t` type
+ * to receive the length.
+ * @return Returns an `std::u16string` object.
*/
const std::u16string ReadString16WithLength(int32_t &len);
/**
- * @brief Read a C++ string(`std::string`) object and its length from this
- * parcel.
+ * @brief Reads a C++ string (`std::string`) object and its length from
+ * this parcel.
*
- * @param len `int32_t`-type variable passed by reference to receive the
- * length.
- * @return An output `std::u8string` object.
+ * @param len Indicates the reference to a variable of the `int32_t` type
+ * to receive the length.
+ * @return Returns an `std::string` object.
*/
const std::string ReadString8WithLength(int32_t &len);
/**
- * @brief Set the read cursor to specified position.
+ * @brief Sets the read cursor to the specified position.
*
- * @param newPosition Specified position represented by offsets relative to
- * the beginning of the data region.
- * @return Return True on success, or false if any error occur.
+ * @param newPosition Indicates the position, represented by the offset
+ * (in bytes) from the beginning of the data region.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool RewindRead(size_t newPosition);
/**
- * @brief Set the write cursor to specified position.
+ * @brief Sets the write cursor to the specified position.
*
- * @param offsets Specified position represented by offsets(Bytes) relative
- * to the beginning of the data region.
- * @return Return True on success, or false if any error occur.
+ * @param offsets Indicates the position, represented by the offset
+ * (in bytes) from the beginning of the data region.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool RewindWrite(size_t offsets);
/**
- * @brief Get current position of read cursor.
+ * @brief Obtains the current position of the read cursor.
*
- * @return Position represented by offsets(Bytes) relative to the beginning
- * of the data region.
+ * @return Returns the position, represented by the offset (in bytes)
+ * from the beginning of the data region.
*/
size_t GetReadPosition();
/**
- * @brief Get current position of write cursor.
+ * @brief Obtains the current position of the write cursor.
*
- * @return Position represented by offsets(Bytes) relative to the beginning
- * of the data region.
+ * @return Returns the position, represented by the offset (in bytes)
+ * from the beginning of the data region.
*/
size_t GetWritePosition();
/**
- * @brief Read a Parcelable(and its subclass) object from this parcel.
+ * @brief Reads a `Parcelable` object and its child class objects
+ * from this parcel.
*
- * @tparam T Specific class type of the output object.
- * @return Object of specific class.
- * @note `nullptr` will return if a '0' is read.
+ * @tparam T Indicates the class type of the output object.
+ * @return Returns the object read.
+ * @note A null pointer will be returned if '0' is read.
*/
template
T *ReadParcelable();
/**
- * @brief Read a Parcelable object from this parcel, and manage it by a
+ * @brief Reads a `Parcelable` object from this parcel and manages it by a
* smart pointer.
*
- * @tparam T Specific class type of the output object.
- * @return Object managed by a smart pointer.
- * @note `nullptr` will return if a '0' is read.
+ * @tparam T Indicates the class type of the output object.
+ * @return Returns the object managed by a smart pointer.
+ * @note A null pointer will be returned if '0' is read.
*/
template
sptr ReadStrongParcelable();
/**
- * @brief Check if it is valid to read an object from current cursor.
+ * @brief Checks whether it is valid to read an object from the current
+ * cursor.
*
- * @return Return true if valid, otherwise return false.
+ * @return Returns `true` if valid; returns `false` otherwise.
*/
bool CheckOffsets();
/**
- * @brief Read an object from this parcel.
+ * @brief Reads an object from this parcel.
*
- * `CheckOffsets()` will call first to check whether it is valid to read an
+ * Call `CheckOffsets()` first to check whether it is valid to read an
* object.
*
- * @tparam T Specific class type of the output object.
- * @return A smart pointer to the object.
- * @note `nullptr` will return if `CheckOffsets()` fail.
+ * @tparam T Indicates the class type of the output object.
+ * @return Returns the smart pointer to the object.
+ * @note A null pointer will be returned if `CheckOffsets()` fails
+ * to be called.
*/
template
sptr ReadObject();
/**
- * @brief Set the Allocator object of this parcel.
+ * @brief Sets a memory allocator for this parcel.
*
- * New Allocator will reallocate the data region to which has been written.
+ * The new allocator will reallocate the data region that has been written.
*
- * @param allocator Specified Allocator object.
- * @return Return True on success, or false if any error occur.
+ * @param allocator Indicates the pointer to an `Allocator` object.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool SetAllocator(Allocator *allocator);
/**
- * @brief Record an array of offsets of the object.
+ * @brief Records an array of positions of this parcel.
*
- * @param offsets A pointer to the input array.
- * @param offsetSize Size of the input array.
- * @note It will return directly if fail.
+ * @param offsets Indicates the pointer to the position array.
+ * @param offsetSize Indicates the size of the position array.
+ * @note The method returns directly if the call fail.
*/
void InjectOffsets(binder_size_t offsets, size_t offsetSize);
/**
- * @brief Deallocate the data region, and reset this parcel.
+ * @brief Deallocates the data region and resets this parcel.
*/
void FlushBuffer();
/**
- * @brief Write an `std::vector` object to this parcel.
+ * @brief Writes an `std::vector` object to this parcel.
*
- * @tparam T1 Specific class type for input vector.
- * @tparam T2 Specific class type for write method of this parcel.
- * @param val Input vector object passed by reference.
- * @param Write Specific `Parcel::Write(T2 value)` method.
- * @return Return True on success, or false if any error occur.
+ * @tparam T1 Indicates the class type for the vector.
+ * @tparam T2 Indicates the class type for the write method of this parcel.
+ * @param val Indicates the reference to the vector.
+ * @param Write Indicates the `Parcel::Write(T2 value)` method.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
template
bool WriteVector(const std::vector &val, bool (Parcel::*Write)(T2));
@@ -689,13 +730,14 @@ public:
bool WriteString16Vector(const std::vector &val);
/**
- * @brief Read an `std::vector` object from this parcel.
+ * @brief Reads an `std::vector` object from this parcel.
*
- * @tparam T1 Specific class type for output vector.
- * @tparam T2 Specific class type for read method of this parcel.
- * @param val Pointer to the output vector object.
- * @param Write Specific `Parcel::Read(T2 value)` method.
- * @return Return True on success, or false if any error occur.
+ * @tparam T1 Indicates the class type for the vector.
+ * @tparam T2 Indicates the class type for the read method of this parcel.
+ * @param val Indicates the pointer to the vector.
+ * @param Write Indicates the `Parcel::Read(T2 value)` method.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
template
bool ReadVector(std::vector *val, bool (Parcel::*Read)(T &));
@@ -728,21 +770,23 @@ public:
protected:
/**
- * @brief Record position of the written object, which are represented by
- * offset from the beginning of the data region.
+ * @brief Records the position of the written object, which is represented
+ * by the offset from the beginning of the data region.
*
- * @param offset Specific position.
- * @return Return True on success, or false if any error occur.
+ * @param offset Indicates the position.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool WriteObjectOffset(binder_size_t offset);
/**
- * @brief Ensure number of the written objects is lower than the capacity of
- * objects.
+ * @brief Ensures that the number of written objects is less than
+ * the capacity of objects.
*
- * If it is full, the capacity will be expanded.
+ * If the data region is full, the capacity will be expanded.
*
- * @return Return True on success, or false if any error occur.
+ * @return Returns `true` if the operation is successful;
+ * returns `false` otherwise.
*/
bool EnsureObjectsCapacity();
@@ -821,7 +865,7 @@ T *Parcel::ReadParcelable()
return T::Unmarshalling(*this);
}
-// Read data from the given parcel into this parcelable object, return sptr.
+// Read data from the given parcel into this parcelable object, and return sptr.
template
sptr Parcel::ReadStrongParcelable()
{
diff --git a/base/include/sorted_vector.h b/base/include/sorted_vector.h
index ed23d8e87422a625ded703b3e96bb1364e45dcee..8da487d3df99a3039178b804efead71ff6d9c380 100644
--- a/base/include/sorted_vector.h
+++ b/base/include/sorted_vector.h
@@ -25,7 +25,7 @@
namespace OHOS {
/**
- * @brief The order of the items in it can be maintained automatically.
+ * @brief Provides a sorted vector, in which all items are sorted automatically.
*/
template
class SortedVector {
@@ -37,7 +37,7 @@ public:
using const_iterator = typename std::vector::const_iterator;
/**
- * @brief Construct a new SortedVector object.
+ * @brief Creates a `SortedVector` object.
*/
SortedVector();
@@ -48,47 +48,50 @@ public:
SortedVector(const std::vector& orivect);
/**
- * @brief Destroy the SortedVector object.
+ * @brief Destroys this `SortedVector` object.
*/
virtual ~SortedVector() {}
/**
- * @brief Copy assignment operator.
+ * @brief An overloaded assignment operator function that assigns a sorted
+ * vector to this vector.
*
- * @param TYPE Type of the items.
- * @param AllowDuplicate Specify if duplicated items are allowed.
+ * @param TYPE Indicates the type of items.
+ * @param AllowDuplicate Specifies whether duplicated items are allowed.
*/
SortedVector& operator=(const SortedVector& rhs);
SortedVector& operator=(const SortedVector& rhs);
/**
- * @brief Empty the vector.
+ * @brief Clears this vector.
*/
inline void Clear() { vec_.clear(); }
/**
- * @brief Return number of items in the vector.
+ * @brief Obtains the number of items in this vector.
*/
inline size_t Size() const { return vec_.size(); }
/**
- * @brief Return whether or not the vector is empty.
+ * @brief Checks whether this vector is empty.
*
- * @return Return true if vector is empty, false otherwise.
+ * @return Returns `true` if the vector is empty; returns `false` otherwise.
*/
inline bool IsEmpty() const { return vec_.empty(); }
/**
- * @brief Return how many items can be stored before reallocating new
- * storage space.
+ * @brief Obtains the capacity of this vector, that is, the number of items
+ * that can be stored before the system reallocates new storage space.
*/
inline size_t Capacity() const { return vec_.capacity(); }
/**
- * @brief Set the vector's capacity to `size`.
+ * @brief Sets the capacity of this vector.
*
- * @return Return `size` if the vector's capacity is changed to `size`,
- * otherwise return `CAPACITY_NOT_CHANGED`(-1).
+ * @param size Indicates the capacity to set.
+ *
+ * @return Returns the capacity if the operation is successful;
+ * returns `CAPACITY_NOT_CHANGED`(-1) otherwise.
*/
ssize_t SetCapcity(size_t size)
{
@@ -102,66 +105,80 @@ public:
// Cstyle access
/**
- * @brief Return a const pointer to the first item of a vector, which is
- * used to access the item.
+ * @brief Accesses the first item in this vector.
+ *
+ * @return Returns a constant pointer to the first item.
*/
inline const TYPE* Array() const { return vec_.data(); }
/**
- * @brief Return a non-const pointer to the first item of a vector that is
- * used to access the item of the vector.
+ * @brief Accesses the first item in this vector while editing it.
+ *
+ * @note When using this function, you should ensure that the vector
+ * is sorted.
*
- * @note When use it , you should make sure it is sorted.
+ * @return Returns a non-constant pointer to the first item.
*/
TYPE* EditArray() { return vec_.data(); }
/**
- * @brief Find the first index of the 'item' value in the vector.
+ * @brief Obtains the index of the first occurrence of an item
+ * in this vector.
+ *
+ * @param item Indicates the item.
+ *
+ * @return Returns the index if the item is found;
+ * returns `NOT_FOUND`(-1) otherwise.
*
- * @param item Target value.
- * @return If found, the index value is returned, otherwise `NOT_FOUND`(-1)
- * is returned.
*/
ssize_t IndexOf(const TYPE& item) const;
/**
- * @brief Find where this `item` should be inserted.
+ * @brief Obtains the index where an item should be inserted into
+ * this vector.
*
- * @param item Target value.
- * @return Return the index where the value should be inserted.
+ * @param item Indicates the item.
+ *
+ * @return Returns the index.
*/
size_t OrderOf(const TYPE& item) const;
/**
- * @brief Access vector items based on the input `index`.
+ * @brief Accesses an item with the specified index.
+ *
+ * @param index Indicates the index.
*
- * @param index `index` value.
- * @return Return the value of the item corresponding to the `index`.
+ * @return Returns the item value.
*/
inline const TYPE& operator[](size_t index) const { return vec_[index]; }
/**
- * @brief Return a reference to the item at the end of the vector.
+ * @brief Obtains the reference to the last item in this vector.
+ *
+ * @return Returns the reference to the last item.
*/
const TYPE& Back() const { return vec_.back(); }
/**
- * @brief Return a reference to the vector starting item.
+ * @brief Obtains the reference to the first item in this vector.
+ *
+ * @return Returns the reference to the first item.
*/
const TYPE& Front() const { return vec_.front(); }
/**
- * @brief Remove the last item of the vector.
+ * @brief Removes the last item from this vector.
*/
void PopBack() { return vec_.pop_back(); }
/**
- * @brief Return the item value of a vector.
+ * @brief Obtains the value of an item with the specified index
+ * in this vector.
*
- * @param index `index` value.
- * @return If `index` is less than 0, the value of
- * vector[vector.size() + `index`] is returned, otherwise the value of
- * vector[`index`] is returned.
+ * @param index Indicates the index.
+ *
+ * @return Returns vector[vector.size() + `index`] if `index` is
+ * less than 0; returns vector[`index`] otherwise.
*/
const TYPE& MirrorItemAt(ssize_t index) const
{
@@ -171,19 +188,22 @@ public:
return *(vec_.begin() + index);
};
- // modify the array
+ // Modify the array.
/**
- * @brief Add a new 'item' in the correct place.
+ * @brief Adds an item to this vector.
*
- * @return Return the position of the new item on success, otherwise it
- * returns `ADD_FAIL`(-1)
+ * @return Returns the index of the item if the operation is successful;
+ * returns `ADD_FAIL`(-1) otherwise.
*/
ssize_t Add(const TYPE& item);
/**
- * @brief Return reference of the item based on `index`.
+ * @brief Obtains the reference to an item with the specified index
+ * in this vector.
+ *
+ * @param index Indicates the index.
*
- * @param index `index` value.
+ * @return Returns the reference to the item.
*/
TYPE& EditItemAt(size_t index)
{
@@ -192,24 +212,26 @@ public:
/**
- * @brief Merge a vector into this one.
+ * @brief Merges a vector into this vector.
*
- * If the value of `AllowDuplicate` is false, it is vec_ to deduplicate.
+ * If `AllowDuplicate` is set to `false`, the current vector should
+ * perform deduplication.
*
- * @param invec The vector to be merged.
- * @return Return the size of the merged vec_.
+ * @param invec Indicates the vector to be merged.
+ *
+ * @return Returns the size of the merged vector.
*/
size_t Merge(const std::vector& invec);
size_t Merge(const SortedVector& sortedVector);
/**
- * @brief If `index` is less than the vector's size, delete the item at
- * `index`.
+ * @brief Erases the item with the specified index from this vector.
+ *
+ * @param index Indicates the index.
*
- * @param index `index` value.
- * @return If `index` is greater than or equal to the size of the vector,
- * the iterator of the last item is returned, otherwise the iterator of the
- * next item of the deleted item is returned.
+ * @return Returns an iterator to the last item if the index is
+ * greater than or equal to the size of the vector;
+ * returns the item next to the deleted item otherwise.
*/
iterator Erase(size_t index)
{
@@ -220,8 +242,10 @@ public:
}
/**
- * @brief An iterator that returns a vector starting item of a non-const
- * type.
+ * @brief Obtains an iterator of the non-const type to the first item
+ * in this vector.
+ *
+ * @return Returns an iterator to the first item.
*/
iterator Begin()
{
@@ -229,7 +253,10 @@ public:
}
/**
- * @brief An iterator that returns the vector starting item of type const.
+ * @brief Obtains an iterator of the const type to the first item
+ * in this vector.
+ *
+ * @return Returns an iterator to the first item.
*/
const_iterator Begin() const
{
@@ -237,8 +264,10 @@ public:
}
/**
- * @brief Return an iterator for an item at the end of a vector of a
- * non-const type.
+ * @brief Obtains an iterator of the non-const type to the last item
+ * in this vector.
+ *
+ * @return Returns an iterator to the last item.
*/
iterator End()
{
@@ -246,8 +275,10 @@ public:
}
/**
- * @brief Return an iterator for the item at the end of a vector of type
- * const.
+ * @brief Obtains an iterator of the const type to the last item
+ * in this vector.
+ *
+ * @return Returns an iterator to the last item.
*/
const_iterator End() const
{
diff --git a/base/include/unique_fd.h b/base/include/unique_fd.h
index 0bc90d90d669d95b440c67174a9ae0d46e855b61..47878b18036fa0d347fd216afbf05ce01c7fe647 100644
--- a/base/include/unique_fd.h
+++ b/base/include/unique_fd.h
@@ -16,10 +16,11 @@
/**
* @file unique_fd.h
*
- * @brief Provide management of file descriptor implemented in c_utils.
+ * @brief Provides APIs to manage file descriptors (FDs) implemented in c_utils.
*
- * Include Manager class UniqueFdAddDeletor, default Deleter class
- * DefaultDeleter and related global operator overload functions.
+ * The manager class `UniqueFdAddDeletor`,
+ * the default deleter class `DefaultDeleter`,
+ * and related global overloaded operator functions are provided.
*/
#ifndef UNIQUE_FD_H
#define UNIQUE_FD_H
@@ -29,21 +30,22 @@
namespace OHOS {
/**
- * @brief Default implement of Deleter, including a static function to close the fd.
+ * @brief Provides the default implementation for a deleter,
+ * including a static function to close FDs.
*
- * Deleter is used for closing the file descriptor. Developer could implement
- * another Deleter to deal with different scenarios./n `Deleter::Close()` will
- * call when a UniqueFdAddDeletor object release the management of an fd, and
- * there's no any other UniqueFdAddDeletor objects to take over it.
+ * The deleter is used for closing FDs. You can implement a deleter to
+ * deal with a different scenario. When `Deleter::Close()` is called to enable
+ * a `UniqueFdAddDeletor` object to release the management of an FD,
+ * the FD can no longer be taken over by other `UniqueFdAddDeletor` objects.
*/
class DefaultDeleter {
public:
/**
- * @brief Default function to close fd.
+ * @brief Default function to close an FD.
*
- * Call `close()` if the input `fd` is valid(>=0).
+ * Call `close()` if the input FD is valid (greater than or equal to 0).
*
- * @param fd Input file descriptor.
+ * @param fd Indicates an FD.
*/
static void Close(int fd)
{
@@ -69,15 +71,15 @@ template
bool operator<(const int& lhs, const UniqueFdAddDeletor& rhs);
/**
- * @brief A file descriptor manager.
+ * @brief Defines an FD manager.
*
- * To take the unique management of a file descriptor, avoiding double close
- * issue. Double close issue may wrongly close the fd which is just opened./n
- * The management of an fd can be delivered between different UniqueFdAddDeletor
- * objects. An fd will be closed if there's no UniqueFdAddDeletor take over the
- * management of it.
+ * To ensure unique management on an FD, avoid the double-close issue,
+ * which may cause a file to be incorrectly closed./n
+ * The management of an FD can be delivered between `UniqueFdAddDeletor`
+ * objects. An FD will be closed if no `UniqueFdAddDeletor` object is available
+ * to take over its management.
*
- * @tparam Deleter Specified Deletor.
+ * @tparam Deleter Indicates a deleter.
* @see DefaultDeleter
*/
template
@@ -96,9 +98,9 @@ class UniqueFdAddDeletor final {
public:
/**
- * @brief Construct UniqueFdAddDeletor with managed fd.
+ * @brief Creates a `UniqueFdAddDeletor` object to manage an FD.
*
- * @param value Fd to be managed.
+ * @param value Indicates the FD to be managed.
*/
explicit UniqueFdAddDeletor(const int& value)
: fd_(value)
@@ -106,7 +108,8 @@ public:
}
/**
- * @brief Construct UniqueFdAddDeletor with managed fd of -1.
+ * @brief Constructor used to create a `UniqueFdAddDeletor` object
+ * with the FD set to `-1`.
*/
UniqueFdAddDeletor()
: fd_(-1)
@@ -114,19 +117,18 @@ public:
}
/**
- * @brief Deconstructor.
+ * @brief Destructor used to destroy this `UniqueFdAddDeletor` object.
*
- * `UniqueFdAddDeletor::Reset(-1)` will call to close the fd
- * and set it to -1.
+ * This function is used to close the FD and set the FD to `-1`.
*/
~UniqueFdAddDeletor() { Reset(-1); }
/**
- * @brief Release the management of current fd, set it to -1.
+ * @brief Releases the management on the current FD and sets it to `-1`.
*
- * @return Return the original fd before release.
- * @note Released fd need to be taken over by another UniqueFdAddDeletor
- * object, otherwise it must be closed manually.
+ * @return Returns the original FD before release.
+ * @note The released FD needs to be taken over by another
+ * `UniqueFdAddDeletor` object; otherwise, it must be closed manually.
*/
int Release()
{
@@ -135,22 +137,24 @@ public:
return tmp;
}
- // this is dangerous, when you use it , you should know it, donot operator on the ret
+ // this is dangerous, when you use it , you should know it,
+ // do not operator on the ret
/**
- * @brief Cast operator overload function.
+ * @brief An overloaded cast operator function.
*
- * E.g. This function will call when pass UniqueFdAddDeletor object to
- * function who requires a parameter of `int`.
+ * This function will be called when passing a `UniqueFdAddDeletor` object
+ * to a function that requires a parameter of `int`.
*
- * @return Return current fd under management.
+ * @return Returns the current FD under management.
*/
operator int() const { return Get(); } // NOLINT
- // this is dangerous, when you use it , you should know it, donot operator on the ret
+ // this is dangerous, when you use it , you should know it, do not operator
+ // on the ret
/**
- * @brief Get current fd under management, but not release it.
+ * @brief Obtains the current FD under management, without releasing it.
*
- * @return Return current fd under management.
+ * @return Returns the current FD.
*/
int Get() const
{
@@ -159,10 +163,10 @@ public:
// we need move fd from one to another
/**
- * @brief Move constuctor. Used for delivering fd between UniqueFdAddDeletor
- * objects.
+ * @brief Move constructor used to deliver the management of an FD from a
+ * `UniqueFdAddDeletor` object to this object.
*
- * @param rhs Source UniqueFdAddDeletor
+ * @param rhs Indicates the source `UniqueFdAddDeletor` object.
*/
UniqueFdAddDeletor(UniqueFdAddDeletor&& rhs)
{
@@ -171,13 +175,14 @@ public:
}
/**
- * @brief Move assignment operator overload function. Used for delivering fd
- * between UniqueFdAddDeletor objects.
+ * @brief Overloaded move assignment operator function used to deliver the
+ * management of an FD from a `UniqueFdAddDeletor` object to this object.
*
- * @param rhs Source UniqueFdAddDeletor
- * @return This object.
- * @note Fd of this object will be closed, then this object will take over
- * the fd managed by `rhs`.
+ * @param rhs Indicates the source `UniqueFdAddDeletor` object.
+ * @return Returns this `UniqueFdAddDeletor` object.
+ * @note The current FD manged by this `UniqueFdAddDeletor` object will be
+ * closed, and this object will take over
+ * the FD originally managed by `rhs`.
*/
UniqueFdAddDeletor& operator=(UniqueFdAddDeletor&& rhs)
{
@@ -187,12 +192,13 @@ public:
}
/**
- * @brief Equal operator overload function.
+ * @brief Checks whether the FD managed by this object and that managed by
+ * the source object are equal.
*
- * Compare of the `rhs` and the fd managed by this object.
+ * @param rhs Indicates the source `UniqueFdAddDeletor` object.
*
- * @param rhs Input value.
- * @return Return true if equal, otherwise return false.
+ * @return Returns `true` if the two FDs are equal; returns `false`
+ * otherwise.
*/
bool operator==(const int& rhs) const
{
@@ -200,12 +206,13 @@ public:
}
/**
- * @brief Not-equal operator overload function.
+ * @brief Checks whether the FD managed by this object and that managed by
+ * the source object are not equal.
*
- * Compare of the `rhs` and the fd managed by this object.
+ * @param rhs Indicates the source `UniqueFdAddDeletor` object.
*
- * @param rhs Input value.
- * @return Return true if not equal, otherwise return false.
+ * @return Returns `true` if the two FDs are not equal; returns `false`
+ * otherwise.
*/
bool operator!=(const int& rhs) const
{
@@ -213,13 +220,13 @@ public:
}
/**
- * @brief Equal-or-Greater-than operator overload function.
+ * @brief Checks whether the FD managed by this object is greater than or
+ * equal to that managed by the source object.
*
- * Compare of the `rhs` and the fd managed by this object.
+ * @param rhs Indicates the source `UniqueFdAddDeletor` object.
*
- * @param rhs Input value.
- * @return Return true if equal to or greater than `rhs`,
- * otherwise return false.
+ * @return Returns `true` if FD managed by this object is greater than or
+ * equal to that managed by the source object; returns `false` otherwise.
*/
bool operator>=(const int& rhs) const
{
@@ -227,13 +234,14 @@ public:
}
/**
- * @brief Greater-than operator overload function.
+ * @brief Checks whether the FD managed by this object is greater than that
+ * managed by the source object.
*
- * Compare of the `rhs` and the fd managed by this object.
+ * @param rhs Indicates the source `UniqueFdAddDeletor` object.
*
- * @param rhs Input value.
- * @return Return true if greater than `rhs`,
- * otherwise return false.
+ * @return Returns `true` if FD managed by this object is greater than that
+ * managed by the source object; returns `false` otherwise.
+ */
*/
bool operator>(const int& rhs) const
{
@@ -241,13 +249,13 @@ public:
}
/**
- * @brief Equal-or-Less-than operator overload function.
+ * @brief Checks whether the FD managed by this object is less than or equal
+ * to that managed by the source object.
*
- * Compare of the `rhs` and the fd managed by this object.
+ * @param rhs Indicates the source `UniqueFdAddDeletor` object.
*
- * @param rhs Input value.
- * @return Return true if equal to or less than `rhs`,
- * otherwise return false.
+ * @return Returns `true` if FD managed by this object is less than or equal
+ * to that managed by the source object; returns `false` otherwise.
*/
bool operator<=(const int& rhs) const
{
@@ -255,13 +263,13 @@ public:
}
/**
- * @brief Less-than operator overload function.
+ * @brief Checks whether the FD managed by this object is less than that
+ * managed by the source object.
*
- * Compare of the `rhs` and the fd managed by this object.
+ * @param rhs Indicates the source `UniqueFdAddDeletor` object.
*
- * @param rhs Input value.
- * @return Return true if less than `rhs`,
- * otherwise return false.
+ * @return Returns `true` if FD managed by this object is less than that
+ * managed by the source object; returns `false` otherwise.
*/
bool operator<(const int& rhs) const
{
@@ -285,14 +293,14 @@ private:
};
/**
- * @brief Global Equal operator overload function.
- *
- * Compare of the `lhs` and the fd managed by `rhs`.
+* @brief Checks whether the FD managed by two objects (specified by `lhs` and
+* `rhs` respectively) are equal.
+*
+ * @tparam Deleter Indicates a deleter.
+ * @param lhs Indicates the first `UniqueFdAddDeletor` object.
+ * @param rhs Indicates the second `UniqueFdAddDeletor` object.
*
- * @tparam Deleter Specified Deletor.
- * @param lhs Input value.
- * @param rhs Input UniqueFdAddDeletor object.
- * @return Return true if equal, otherwise return false.
+ * @return Returns `true` if the two FDs are equal; returns `false` otherwise.
* @see DefaultDeleter
*/
template
@@ -302,14 +310,15 @@ bool operator==(const int& lhs, const UniqueFdAddDeletor& rhs)
}
/**
- * @brief Global Not-equal operator overload function.
- *
- * Compare of the `lhs` and the fd managed by `rhs`.
+* @brief Checks whether the FD managed by two objects (specified by `lhs` and
+* `rhs` respectively) are not equal.
+*
+ * @tparam Deleter Indicates a deleter.
+ * @param lhs Indicates the first `UniqueFdAddDeletor` object.
+ * @param rhs Indicates the second `UniqueFdAddDeletor` object.
*
- * @tparam Deleter Specified Deletor.
- * @param lhs Input value.
- * @param rhs Input UniqueFdAddDeletor object.
- * @return Return true if not equal, otherwise return false.
+ * @return Returns `true` if the two FDs are not equal; returns `false`
+ * otherwise.
* @see DefaultDeleter
*/
template
@@ -319,16 +328,16 @@ bool operator!=(const int& lhs, const UniqueFdAddDeletor& rhs)
}
/**
- * @brief Global Equal-or-Greater-than operator overload function.
+ * @brief Checks whether the FD managed by `lhs` is greater than or equal to
+ * that managed by `rhs`.
*
- * Compare of the `lhs` and the fd managed by `rhs`.
+ * @tparam Deleter Indicates a deleter.
+ * @param lhs Indicates the first `UniqueFdAddDeletor` object.
+ * @param rhs Indicates the second `UniqueFdAddDeletor` object.
*
- * @tparam Deleter Specified Deletor.
- * @param lhs Input value.
- * @param rhs Input UniqueFdAddDeletor object.
+ * @return Returns `true` if the FD managed by `lhs` is greater than or equal to
+ * that managed by `rhs`; returns `false` otherwise.
* @see DefaultDeleter
- * @return Return true if `lhs` is equal to
- * or greater than fd managed by `rhs`.
*/
template
bool operator>=(const int& lhs, const UniqueFdAddDeletor& rhs)
@@ -337,15 +346,16 @@ bool operator>=(const int& lhs, const UniqueFdAddDeletor& rhs)
}
/**
- * @brief Global Greater-than operator overload function.
+ * @brief Checks whether the FD managed by `lhs` is greater than that
+ * managed by `rhs`.
*
- * Compare of the `lhs` and the fd managed by `rhs`.
+ * @tparam Deleter Indicates a deleter.
+ * @param lhs Indicates the first `UniqueFdAddDeletor` object.
+ * @param rhs Indicates the second `UniqueFdAddDeletor` object.
*
- * @tparam Deleter Specified Deletor.
- * @param lhs Input value.
- * @param rhs Input UniqueFdAddDeletor object.
+ * @return Returns `true` if the FD managed by `lhs` is greater than that
+ * managed by `rhs`; returns `false` otherwise.
* @see DefaultDeleter
- * @return Return true if `lhs` is greater than fd managed by `rhs`.
*/
template
bool operator>(const int& lhs, const UniqueFdAddDeletor& rhs)
@@ -354,16 +364,16 @@ bool operator>(const int& lhs, const UniqueFdAddDeletor& rhs)
}
/**
- * @brief Global Equal-or-Less-than operator overload function.
+ * @brief Checks whether the FD managed by `lhs` is less than or equal to that
+ * managed by `rhs`.
*
- * Compare of the `lhs` and the fd managed by `rhs`.
+ * @tparam Deleter Indicates a deleter.
+ * @param lhs Indicates the first `UniqueFdAddDeletor` object.
+ * @param rhs Indicates the second `UniqueFdAddDeletor` object.
*
- * @tparam Deleter Specified Deletor.
- * @param lhs Input value.
- * @param rhs Input UniqueFdAddDeletor object.
+ * @return Returns `true` if the FD managed by `lhs` is less than or equal to
+ * that managed by `rhs`; returns `false` otherwise.
* @see DefaultDeleter
- * @return Return true if `lhs` is equal to
- * or less than fd managed by `rhs`.
*/
template
bool operator<=(const int& lhs, const UniqueFdAddDeletor& rhs)
@@ -372,15 +382,16 @@ bool operator<=(const int& lhs, const UniqueFdAddDeletor& rhs)
}
/**
- * @brief Global Equal-or-Greater-than operator overload function.
+ * @brief Checks whether the FD managed by `lhs` is less than that
+ * managed by `rhs`.
*
- * Compare of the `lhs` and the fd managed by `rhs`.
+ * @tparam Deleter Indicates a deleter.
+ * @param lhs Indicates the first `UniqueFdAddDeletor` object.
+ * @param rhs Indicates the second `UniqueFdAddDeletor` object.
*
- * @tparam Deleter Specified Deletor.
- * @param lhs Input value.
- * @param rhs Input UniqueFdAddDeletor object.
+ * @return Returns `true` if the FD managed by `lhs` is less than that
+ * managed by `rhs`; returns `false` otherwise.
* @see DefaultDeleter
- * @return Return true if `lhs` is less than fd managed by `rhs`.
*/
template
bool operator<(const int& lhs, const UniqueFdAddDeletor& rhs)