From e04790b1cf3139eb9ddeb22465642870f012b24b Mon Sep 17 00:00:00 2001 From: Gloria Date: Mon, 22 May 2023 15:16:50 +0800 Subject: [PATCH] Polished three header files Issue: I71TKP Signed-off-by: Gloria --- base/include/parcel.h | 524 +++++++++++++++++++---------------- base/include/sorted_vector.h | 153 ++++++---- base/include/unique_fd.h | 237 ++++++++-------- 3 files changed, 500 insertions(+), 414 deletions(-) diff --git a/base/include/parcel.h b/base/include/parcel.h index 3ce1b4d..89ac76c 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 ed23d8e..8da487d 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 0bc90d9..47878b1 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) -- Gitee