From 6ea2d69cf9a7f96ed17bb0a49d40ec2adc85882d Mon Sep 17 00:00:00 2001 From: "ester.zhou" Date: Thu, 11 May 2023 19:56:24 +0800 Subject: [PATCH] update docs (0511) Signed-off-by: ester.zhou --- base/include/ashmem.h | 160 ++++++++++++---------- base/include/common_errors.h | 10 +- base/include/common_mapped_file_errors.h | 12 +- base/include/common_timer_errors.h | 23 ++-- base/include/datetime_ex.h | 64 +++++---- base/include/errors.h | 25 ++-- base/include/flat_obj.h | 6 +- base/include/nocopyable.h | 6 +- base/include/observer.h | 43 +++--- base/include/rwlock.h | 67 ++++----- base/include/string_ex.h | 166 ++++++++++++----------- base/include/timer.h | 87 ++++++------ 12 files changed, 353 insertions(+), 316 deletions(-) diff --git a/base/include/ashmem.h b/base/include/ashmem.h index f7d855e..6d66c4d 100644 --- a/base/include/ashmem.h +++ b/base/include/ashmem.h @@ -16,8 +16,8 @@ /** * @file ashmem.h * - * @brief Provide class Ashmem implemented in c_utils to operate the - * Anonymous Shared Memory(Ashmem). + * @brief Provides the Ashmem class implemented in c_utils to operate the + * Anonymous Shared Memory (Ashmem). */ #ifndef UTILS_BASE_ASHMEM_H @@ -30,164 +30,174 @@ namespace OHOS { /** - * @brief Create ashmem in kernel with specified name and size. + * @brief Creates an Ashmem region in the kernel. * - * @param name Name for identifying the ashmem in kernel. - * @param size Size of the ashmem region. - * @return File descriptor of the ashmem. + * @param name Indicates the pointer to the name that will be + * copied and assigned to the Ashmem region in the kernel. + * @param size Indicates the size of the Ashmem region to create. + * @return Returns the file descriptor of the Ashmem region. */ int AshmemCreate(const char *name, size_t size); /** - * @brief Set protection flag of specified ashmem region in kernel. - - * @param fd Corresponding file descriptor. - * @param prot Value of protection flag. - * @return Return 0 on success, -1 on failure. + * @brief Sets the protection flag of an Ashmem region in the kernel. + * + * @param fd Indicates the file descriptor of an Ashmem region. + * @param prot Indicates the value of the protection flag. + * @return Returns 0 if the operation is successful; + * returns -1 otherwise. */ int AshmemSetProt(int fd, int prot); /** - * @brief Get size of specified ashmem region in kernel. + * @brief Obtains the size of a specific Ashmem region in the kernel. * - * @param fd Corresponding file descriptor. - * @return Size of ashmem. + * @param fd Indicates the file descriptor of an Ashmem region. + * @return Returns the size of the Ashmem region. */ int AshmemGetSize(int fd); /** - * @brief Ashmem implemented in c_utils, to operate the - * Anonymous Shared Memory(Ashmem). + * @brief Provides the Ashmem class implemented in c_utils to + * operate the Anonymous Shared Memory (Ashmem). * - * Including create, map an ashmem region and thus write/read to/from it, etc. + * You can use the interfaces in this class to create Ashmem regions + * and map them to implement write and read operations. * - * @note Ashmem object should be unmapped and closed manually, though managed - * by smart pointer. + * @note Ashmem regions should be unmapped and closed manually, + * though managed by a smart pointer. */ class Ashmem : public virtual RefBase { public: /** - * @brief Create an Ashmem object with specified name and region size. + * @brief Creates an Ashmem region in the kernel. + * + * The /dev/ashmem file will be opened, whose file + * descriptor will be held by the created Ashmem region. * - * File '/dev/ashmem' will be opened whose file descriptor will be held by - * this Ashmem object. + * @param name Indicates the pointer to the name that will be + * copied and assigned to the Ashmem region in the kernel. + * @param size Indicates the size of the Ashmem region. + * @return Returns the created Ashmem region referenced by a + * smart pointer. + * @note Before writing/reading data in the region, use `MapAshmem()`. * - * @param name Name for identifying the ashmem in kernel. - * @param size Size of the ashmem region. - * @return An Ashmem object referenced by a smart pointer. - * @note Memory has not been mapped, use `MapAshmem()` before - * writing/reading. */ static sptr CreateAshmem(const char *name, int32_t size); /** - * @brief Close the ashmem(i.e. close it via file descriptor). + * @brief Closes this Ashmem region (through the file descriptor). * * All inner parameters will be cleared. * - * @note An ashmem will be unmapped first by `UnmapAshmem()` before close. + * @note An Ashmem region will be unmapped by `UnmapAshmem()` + * before being closed. */ void CloseAshmem(); /** - * @brief Map the ashmem region in the kernel to user space. + * @brief Maps this Ashmem region in the kernel to user space. * - * @param mapType Protection flag of the mapped region in user space. - * @return True if mapping successful. + * @param mapType Indicates the protection flag of the mapped region in + * user space. + * @return Returns true if mapping is successful. */ bool MapAshmem(int mapType); /** - * @brief Map the ashmem region in Read/Write mode. + * @brief Maps this Ashmem region in read/write mode. * * It calls `MapAshmem(PROT_READ | PROT_WRITE)`. * - * @return True if mapping successful. + * @return Returns true if mapping is successful. */ bool MapReadAndWriteAshmem(); /** - * @brief Map the ashmem region in Read-Only mode. + * @brief Maps this Ashmem region in read-only mode. * * It calls `MapAshmem(PROT_READ)`. * - * @return True if mapping successful. + * @return Returns true if mapping is successful. */ bool MapReadOnlyAshmem(); /** - * @brief Unmap the ashmem. + * @brief Unmaps this Ashmem region. * - * Unmap when mapped ashmem exists, protection flag will be cleared - * meanwhile. + * Unmapping works only when the Ashmem region has been mapped. + * It will clear the protection flag. */ void UnmapAshmem(); /** - * @brief Set the protection flag of ashmem region in kernel. + * @brief Sets the protection flag of this Ashmem region. * - * @param protectionType Value of protection flag. - * @return True if set successful. + * @param protectionType Indicates the value of the protection flag. + * @return Returns True if the operation is successful. */ bool SetProtection(int protectionType); /** - * @brief Get the protection flag of ashmem region in kernel. + * @brief Obtains the protection flag of this Ashmem region. * - * @return Value of protection flag. Refer to linux manual. + * @return Returns the protection flag. For details, see the Linux manual. */ int GetProtection(); /** - * @brief Get the size of ashmem region in kernel. + * @brief Obtains the size of this Ashmem region. * - * @return Value of size. + * @return Returns the size. */ int32_t GetAshmemSize(); /** - * @brief Write data to the `offset` position of ashmem region. - * - * Bounds and protection flag will be checked. - * - * @param data Pointer to input data. - * @param size Size of the input data(bytes). - * @param offset Offset from beginning of the region. - * @return True if writting successful. False if data to be write overflows - * or protection flag is illegal. - * @note Require write authority of both ashmem in kernel and the mapped - * one in user space. + * @brief Writes data to the `offset` position of this Ashmem region. + * + * Bounds and the protection flag will be checked. + * + * @param data Indicates the pointer to the data to write. + * @param size Indicates the size of the data to write, in bytes. + * @param offset Indicates the offset from the start position of the + * Ashmem region. + * @return Returns True if the operation is successful; returns + * False if overflow occurs or the protection flag is illegal. + * @note This operation requires the write permission on both the + * Ashmem region in the kernel and the mapped region in user space. */ bool WriteToAshmem(const void *data, int32_t size, int32_t offset); /** - * @brief Read data from the `offset` position of ashmem region. + * @brief Reads data from the `offset` position of this Ashmem region. * - * Bounds and protection flag will be checked. + * Bounds and the protection flag will be checked. * - * @param size Size of data to be read(bytes). - * @param offset Offset from beginning of the region. - * @return Void-type pointer to the data. `nullptr` returns if data to be - * read overflows or protection flag is illegal. - * @note Require read authority of both ashmem in kernel and the mapped one - * in user space. + * @param size Indicates the size of the data to read, in bytes. + * @param offset Indicates the offset from the start position of + * the Ashmem region. + * @return Returns the void-type pointer to the data. `nullptr` is returned + * if overflow occurs or the protection flag is illegal. + * @note This operation requires the read permission on both the + * Ashmem region in the kernel and the mapped region in user space. */ const void *ReadFromAshmem(int32_t size, int32_t offset); /** - * @brief Construct a new Ashmem object. + * @brief Creates an Ashmem region. * - * @param fd File descriptor of an ashmem in kenrel. - * @param size Size of the corresponding ashmem region in kernel. + * @param fd Indicates the file descriptor of the Ashmem region + * in the kenrel. + * @param size Indicates the size of the Ashmem region. */ Ashmem(int fd, int32_t size); ~Ashmem() override; /** - * @brief Get file descriptor of the corresponding ashmem in kernel. + * @brief Obtains the file descriptor of this Ashmem region in the kernel. * - * @return Corresponding file descriptor of this Ashmem object. It will be - * 0 when ashmem is closed. + * @return Returns the file descriptor. The value 0 is returned + * if the Ashmem region is closed. */ int GetAshmemFd() const { @@ -195,10 +205,10 @@ public: }; private: - int memoryFd_; // corresponding file descriptor of ashmem. - int32_t memorySize_; // size of ashmem. - int flag_; // protection flag of ashmem in user space. - void *startAddr_; // start address of ashmem region. + int memoryFd_; // File descriptor of the Ashmem region. + int32_t memorySize_; // Size of the Ashmem region. + int flag_; // Protection flag of the Ashmem region in user space. + void *startAddr_; // Start address of the Ashmem region. bool CheckValid(int32_t size, int32_t offset, int cmd); }; } // namespace OHOS diff --git a/base/include/common_errors.h b/base/include/common_errors.h index 02553a2..89a4666 100644 --- a/base/include/common_errors.h +++ b/base/include/common_errors.h @@ -16,8 +16,8 @@ /** * @file common_errors.h * - * @brief Provide value of 'Module' segment of ErrCode for all modules in - * commonlibrary subsystem. + * @brief Provides values of the Module segment in ErrCode + * for all modules in the commonlibrary subsystem. */ #ifndef UTILS_COMMON_ERRORS_H @@ -35,12 +35,12 @@ namespace Utils { * |Field|Reserved| Subsystem | Module | Code | * +-----+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ * - * In this file, subsystem is "SUBSYS_COMMON". + * In this file, the subsystem is "SUBSYS_COMMON". */ /** - * @brief Value of 'Module' segment of ErrCode for modules in commonlibrary - * subsystem. + * @brief Enumerates the values of the Module segment of ErrCode + * for modules in the commonlibrary subsystem. * * @var MODULE_DEFAULT Default * @var MODULE_TIMER Timer(timer.h) diff --git a/base/include/common_mapped_file_errors.h b/base/include/common_mapped_file_errors.h index f672aec..1f50c8a 100644 --- a/base/include/common_mapped_file_errors.h +++ b/base/include/common_mapped_file_errors.h @@ -16,8 +16,8 @@ /** * @file common_mapped_file_errors.h * - * @brief Provide value of 'Code' segment of ErrCode for 'MappedFile' module in - * commonlibrary subsystem. + * @brief Provides the values of the Code segment in ErrCode + * for the MappedFile module in the commonlibrary subsystem. */ #ifndef UTILS_COMMON_TIMER_ERRORS_H @@ -39,14 +39,16 @@ namespace Utils { * |Field|Reserved| Subsystem | Module | Code | * +-----+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ * - * In this file, subsystem is "SUBSYS_COMMON" and module is "MODULE_MAPPED_FILE". + * In this file, the subsystem is "SUBSYS_COMMON", and the module is + * "MODULE_MAPPED_FILE". */ using ErrCode = int; -// offset of mapped file module error, only be used in this file. +// The error codes can be used only for the MappedFile module. /** - * @brief Base ErrCode of module 'MappedFile' in commonlibrary subsystem. + * @brief Provides the base error codes of the MappedFile module + * in the commonlibrary subsystem. */ constexpr ErrCode COMMON_MAPPED_FILE_ERR_OFFSET = ErrCodeOffset(SUBSYS_COMMON, MODULE_MAPPED_FILE); diff --git a/base/include/common_timer_errors.h b/base/include/common_timer_errors.h index 9c90ccd..522a435 100644 --- a/base/include/common_timer_errors.h +++ b/base/include/common_timer_errors.h @@ -16,8 +16,8 @@ /** * @file common_timer_errors.h * - * @brief Provide value of 'Code' segment of ErrCode for 'Timer' module in - * commonlibrary subsystem. + * @brief Provides the values of the Code segment in ErrCode + * for the Timer module in the commonlibrary subsystem. */ #ifndef UTILS_COMMON_TIMER_ERRORS_H @@ -39,24 +39,27 @@ namespace Utils { * |Field|Reserved| Subsystem | Module | Code | * +-----+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ * - * In this file, subsystem is "SUBSYS_COMMON" and module is "MODULE_TIMER". + * In this file, the subsystem is "SUBSYS_COMMON", and the module is + * "MODULE_TIMER". */ using ErrCode = int; -// offset of timer module error, only be used in this file. +// The error codes can be used only for the Timer module. /** - * @brief Base ErrCode of module 'Timer' in commonlibrary subsystem. + * @brief Provides the base error codes of the Timer module + * in the commonlibrary subsystem. */ constexpr ErrCode COMMON_TIMER_ERR_OFFSET = ErrCodeOffset(SUBSYS_COMMON, MODULE_TIMER); /** - * @brief Value of 'Code' segment of ErrCode for 'Timer'. + * @brief Enumerates the values of the Code segment in ErrCode + * for the Timer module. * - * @var TIMER_ERR_OK Success. - * @var TIMER_ERR_DEAL_FAILED Deal failed. - * @var TIMER_ERR_BADF Bad file descriptor. - * @var TIMER_ERR_INVALID_VALUE Invalid value. + * @var TIMER_ERR_OK Indicates an operation success. + * @var TIMER_ERR_DEAL_FAILED Indicates an operation failure. + * @var TIMER_ERR_BADF Indicates a bad file descriptor. + * @var TIMER_ERR_INVALID_VALUE Indicates an invalid value. */ enum { TIMER_ERR_OK = 0, diff --git a/base/include/datetime_ex.h b/base/include/datetime_ex.h index b6ae42e..7acd825 100644 --- a/base/include/datetime_ex.h +++ b/base/include/datetime_ex.h @@ -24,21 +24,21 @@ namespace OHOS { * Here is the definition of strct tm: * struct tm * { - * int tm_sec; // Seconds. [0-60] (1 leap second) - * int tm_min; // Minutes. [0-59] - * int tm_hour; // Hours. [0-23] - * int tm_mday; // Day. [1-31] - * int tm_mon; // Month. [0-11] + * int tm_sec; // Seconds. Value range: [0-60] (1 leap second) + * int tm_min; // Minutes. Value range: [0-59] + * int tm_hour; // Hours. Value range: [0-23] + * int tm_mday; // Day. Value range: [1-31] + * int tm_mon; // Month. Value range: [0-11] * int tm_year; // Year - 1900. - * int tm_wday; // Day of week. [0-6] - * int tm_yday; // Days in year.[0-365] - * int tm_isdst; // DST. [-1/0/1] + * int tm_wday; // Day of week. Value range: [0-6] + * int tm_yday; // Days in year. Value range: [0-365] + * int tm_isdst; // DST. Value range: [-1/0/1] * #ifdef __USE_BSD - * long int tm_gmtoff; //Seconds east of UTC. - * __const char *tm_zone; //Timezone abbreviation. + * long int tm_gmtoff; // Seconds east of UTC. + * __const char *tm_zone; // Time zone abbreviation. * #else - * long int __tm_gmtoff; //Seconds east of UTC. - * __const char *__tm_zone; //Timezone abbreviation. + * long int __tm_gmtoff; // Seconds east of UTC. + * __const char *__tm_zone; // Time zone abbreviation. * #endif * }; */ @@ -53,7 +53,7 @@ constexpr int SECONDS_PER_HOUR = 3600; // 60 * 60 constexpr int SECONDS_PER_DAY = 86400; // 60 * 60 * 24 /** - * @brief Convert seconds to nanoseconds. + * @brief Converts seconds to nanoseconds. */ constexpr inline int64_t SecToNanosec(int64_t sec) { @@ -61,7 +61,7 @@ constexpr inline int64_t SecToNanosec(int64_t sec) } /** - * @brief Convert milliseconds to nanoseconds. + * @brief Converts milliseconds to nanoseconds. */ constexpr inline int64_t MillisecToNanosec(int64_t millise) { @@ -69,7 +69,7 @@ constexpr inline int64_t MillisecToNanosec(int64_t millise) } /** - * @brief Convert microseconds to nanoseconds. + * @brief Converts microseconds to nanoseconds. */ constexpr inline int64_t MicrosecToNanosec(int64_t microsec) { @@ -77,7 +77,7 @@ constexpr inline int64_t MicrosecToNanosec(int64_t microsec) } /** - * @brief Convert nanoseconds to seconds. + * @brief Converts nanoseconds to seconds. */ constexpr inline int64_t NanosecToSec(int64_t nanosec) { @@ -93,7 +93,7 @@ constexpr inline int64_t NanosecToMillisec(int64_t nanosec) } /** - * @brief Convert nanoseconds to microseconds. + * @brief Converts nanoseconds to microseconds. */ constexpr inline int64_t NanosecToMicrosec(int64_t nanosec) { @@ -101,48 +101,52 @@ constexpr inline int64_t NanosecToMicrosec(int64_t nanosec) } /** - * @brief Get seconds from 1970 to now. + * @brief Obtains the number of seconds from 00:00:00 on January 1, 1970 + * to the current time. */ int64_t GetSecondsSince1970ToNow(); /** - * @brief Get seconds from 1970 to inputtime. + * @brief Obtains the number of seconds from 00:00:00 on January 1, 1970 + * to the specified point of time. */ int64_t GetSecondsSince1970ToPointTime(struct tm inputTm); /** - * @brief Get seconds between inputTm1 and inputTm2. + * @brief Obtains the number of seconds between inputTm1 and inputTm2. */ int64_t GetSecondsBetween(struct tm inputTm1, struct tm inputTm2); /** - * @brief Get days from 1970 to now. + * @brief Obtains the number of days from January 1, 1970 to the current date. */ int64_t GetDaysSince1970ToNow(); /** - * @brief Get current timezone. + * @brief Obtains the local time zone. * - * @param timezone Today the world is divided into 24 timezones, they are - * medium timezone (zero timezone), east 1-12 timezone, west 1-12 timezone.The - * East time zone is +1 to +12 and the West time zone is -1 to -12. - * @return return true if get success, else false. + * @param timezone Indicates the time zone. A total of 24 time zones are + * supported, with the eastern time zones represented by +1 to +12, and + * the western time zones -1 to -12. + * @return Returns true if the operation is successful; + * returns false otherwise. */ bool GetLocalTimeZone(int& timezone); /** - * @brief Get current time. - * @return return true if get success, else false. + * @brief Obtains the current time. + * @return Returns true if the operation is successful; + * returns false otherwise. */ bool GetSystemCurrentTime(struct tm* curTime); /** - * @brief Get current milliseconds since the system was started. + * @brief Obtains the number of milliseconds since the system was started. */ int64_t GetTickCount(); /** - * @brief Get current microseconds since the system was started. + * @brief Obtains the number of microseconds since the system was started. */ int64_t GetMicroTickCount(); } diff --git a/base/include/errors.h b/base/include/errors.h index 56f61fc..121c56f 100644 --- a/base/include/errors.h +++ b/base/include/errors.h @@ -16,7 +16,7 @@ /** * @file errors.h * - * @brief Provide format of error code in OpenHarmony. + * @brief Provides format of error code in OpenHarmony. */ #ifndef UTILS_BASE_ERRORS_H @@ -39,7 +39,8 @@ namespace OHOS { using ErrCode = int; /** - * @brief Value of 'Subsystem' segment of ErrCode for every subsystem. + * @brief Enumerates the values of the Subsystem segment + * of ErrCode for every subsystem. */ enum { SUBSYS_COMMON = 0, @@ -97,13 +98,13 @@ enum { // be used to init the subsystem errorno. /** - * @brief Generate base error code for a specified module in specified - * subsystem. + * @brief Generates the base error codes for a specified module + * in specified subsystem. * - * @param subsystem Value of 'Subsystem' segment. - * @param module Value of 'Module' segment, - * which is 0 by default. - * @return Return base ErrCode for specified module. + * @param subsystem Indicates the subsystem. + * @param module Indicates the module. + * The default value is 0. + * @return Returns the base error codes of the specified module. */ constexpr ErrCode ErrCodeOffset(unsigned int subsystem, unsigned int module = 0) { @@ -114,14 +115,14 @@ constexpr ErrCode ErrCodeOffset(unsigned int subsystem, unsigned int module = 0) // offset of common error, only be used in this file. /** - * @brief Base ErrCode of common(valid for all modules) - * in commonlibrary subsystem. + * @brief Provides the common base error codes, which apply to all modules, + * in the commonlibrary subsystem. */ constexpr ErrCode BASE_ERR_OFFSET = ErrCodeOffset(SUBSYS_COMMON); /** - * @brief Value of common 'Code' segment of ErrCode - * in commonlibrary subsystem. + * @brief Enumerates the common base error codes + * in the commonlibrary subsystem. * * @see Related error codes defined in errno.h */ diff --git a/base/include/flat_obj.h b/base/include/flat_obj.h index 5d715ff..1691998 100644 --- a/base/include/flat_obj.h +++ b/base/include/flat_obj.h @@ -16,10 +16,10 @@ /** * @file flat_obj.h * - * @brief Define types and structures for reading and writing object in parcel. + * @brief Defines types and structures for reading and writing objects in parcels. * - * Types are platform-sensitive. Structures is only used for checking the - * validity of data in parcel, not for saving and using of data. + * Types are platform-sensitive. Structures are only used for checking the + * validity of data in parcels, not for saving and using of data. */ #ifndef UTILS_BASE_FLAT_OBJ_H #define UTILS_BASE_FLAT_OBJ_H diff --git a/base/include/nocopyable.h b/base/include/nocopyable.h index dfb96cf..75876b5 100644 --- a/base/include/nocopyable.h +++ b/base/include/nocopyable.h @@ -19,21 +19,21 @@ namespace OHOS { /** - * @brief Disable the copy and move construct/assignment method. + * @brief Disables the copy and move construct/assignment method. */ #define DISALLOW_COPY_AND_MOVE(className)\ DISALLOW_COPY(className);\ DISALLOW_MOVE(className) /** - * @brief Disable the copy construct/assignment method. + * @brief Disables the copy construct/assignment method. */ #define DISALLOW_COPY(className)\ className(const className&) = delete;\ className& operator= (const className&) = delete /** - * @brief Disable the move construct/assignment method. + * @brief Disables the move construct/assignment method. */ #define DISALLOW_MOVE(className)\ className(className&&) = delete;\ diff --git a/base/include/observer.h b/base/include/observer.h index 46d9700..35811af 100644 --- a/base/include/observer.h +++ b/base/include/observer.h @@ -24,7 +24,7 @@ namespace OHOS { /** - * @brief Parameters and data required to call the update method. + * @brief Provides the parameters and data required to call the update method. */ struct ObserverArg { public: @@ -32,73 +32,75 @@ public: }; /** - * @brief Observer class. + * @brief Implements the Observer class. */ class Observer; /** - * @brief Observed class. + * @brief Implements the observed class. */ class Observable { public: virtual ~Observable() = default; /** - * @brief Add the specified observer to the set of observers. + * @brief Adds the specified observer to the set of observers. * - * If `o` is valid and does not exist in the observer set, the observer - * will be added, otherwise this function will return directly. + * If `o` is valid and does not exist in the observer set, the observer + * will be added; otherwise, this function will return directly. */ void AddObserver(const std::shared_ptr& o); /** - * @brief Remove the observer passed in from the parameter. + * @brief Removes the specified observer. */ void RemoveObserver(const std::shared_ptr& o); /** - * @brief Remove all observers. + * @brief Removes all observers. */ void RemoveAllObservers(); /** - * @brief Notify all observers without data transmission. + * @brief Notifies all observers with no data passed. * - * Equivalent to NotifyObservers(nullptr). + * This function is equivalent to NotifyObservers(nullptr). */ void NotifyObservers(); /** - * @brief Notify all observers, and pass the data 'arg' to the observer. + * @brief Notifies all observers, with the data 'arg' passed to + * the observers. * - * If the `changed_` is true, call the `Update()` function to notify all + * If `changed_` is true, call the `Update()` function to notify all * observers to respond. * - * @param arg Parameters and data maybe used for Observer::Update(). + * @param arg Indicates the parameters and data to be used for + * Observer::Update(). * @see ObserverArg. */ void NotifyObservers(const ObserverArg* arg); /** - * @brief Get the number of observers. + * @brief Obtains the number of observers. */ int GetObserversCount(); protected: /** - * @brief Get the state of this Observable object. + * @brief Obtains the state of this Observable object. * - * @return The value of `changed_`. + * @return Returns the value of `changed_`. */ bool HasChanged(); /** - * @brief Set the state of this Observable object to true. + * @brief Sets the state of this Observable object to true. */ void SetChanged(); /** - * @brief Set the state of this Observable object to false. + * @brief Set the state of this Observable object to false. */ void ClearChanged(); @@ -114,9 +116,10 @@ class Observer { public: virtual ~Observer() = default; /** - * @brief The observer's interface to update itself. + * @brief Updates this observer. * - * It will be called when this object is notified by an Observable object. + * It will be called when this observer is notified by an + * Observable object. */ virtual void Update(const Observable* o, const ObserverArg* arg) = 0; }; diff --git a/base/include/rwlock.h b/base/include/rwlock.h index a3c7a1d..14b60ed 100644 --- a/base/include/rwlock.h +++ b/base/include/rwlock.h @@ -16,7 +16,7 @@ /** * @file rwlock.h * - * @brief A file contains interfaces of RWLock in c_utils. + * @brief Provides interfaces of RWLock in c_utils. */ #ifndef UTILS_RWLOCK_H @@ -31,16 +31,17 @@ namespace OHOS { namespace Utils { /** - * @brief RWLock promise reading and writing thread-safe. + * @brief Implements the RWLock class to ensure that read and write + * operations are thread-safe. * - * Under RWLock, writing and writing are mutually exclusive, - * writing and reading are mutually exclusive. - * However, reading and reading are not mutually exclusive. + * Under RWLock, write operations are mutually exclusive, + * and read and write operations are mutually exclusive. + * However, read operations are not mutually exclusive. */ class RWLock : NoCopyable { public: /** - * @brief Enumeration of lock status. + * @brief Enumerates the lock states. */ enum LockStatus { LOCK_STATUS_WRITE = -1, @@ -48,70 +49,70 @@ public: }; /** - * @brief Construct a RWLock object. + * @brief Creates an RWLock object. * - * @param writeFirst Specifies the mode of RWLock, whether it is write-first. + * @param writeFirst Indicates whether the RWLock object is write-first. */ RWLock() : RWLock(true) {} explicit RWLock(bool writeFirst); /** - * @brief Destroy a RWLock object. + * @brief Destroys this RWLock object. */ ~RWLock() override {} /** - * @brief Acquire a read lock + * @brief Obtains a read lock. * - * If the thread has acquired the write lock, return directly. - * In 'write-first' mode, the state must be non-write locked - * and no other threads are waiting to write to acquire a read lock. - * If it is not write priority, you only need the current state to be - * non-write-locked to acquire a read lock. + * If the thread has obtained a write lock, this function returns directly. + * In write-first mode, a read lock can be obtained only when the state + * is non-write-locked and no other threads are waiting to write data. + * In other modes, a read lock can be obtained when the state is + * non-write-locked. */ void LockRead(); /** - * @brief Release the read lock. + * @brief Releases the read lock. * - * If the "write lock" has been acquired before, - * LockRead() will return directly, thus, - * this method will also be returned directly when called. + * If the write lock has been obtained before, + * LockRead() will return directly. + * This function will also return directly when called. */ void UnLockRead(); /** - *@brief Acquire a write lock + *@brief Obtains a write lock * - * If the thread has acquired a "write lock", LockWrite() will return directly - * to avoid acquiring a lock, because write locks are "exclusive locks". - * Only when no other thread has acquired a read lock or a write lock, - * the write lock can be acquired; otherwise wait. + * If the thread has obtained a write lock, this function returns directly + * to avoid acquiring a lock, because write locks are exclusive. + * The write lock can be obtained only when no other thread has obtained a read + * lock or a write lock; otherwise, the thread shall wait. */ void LockWrite(); /** - * @brief Release the write lock. + * @brief Releases the write lock. * - * If the thread does not obtain a "write lock" , it returns directly. + * If the thread has not obtained a write lock, this function returns directly. */ void UnLockWrite(); private: - bool writeFirst_; // The flag of write mode, true means write priority mode - std::thread::id writeThreadID_; // The ID of write Thread + bool writeFirst_; // Whether the thread is write-first. The value true means that the thread is write-first. + std::thread::id writeThreadID_; // ID of the write thread. - // Resource lock counter, -1 is write state, 0 is free state, and greater than 0 is shared read state + // Resource lock counter. -1 indicates the write state, 0 indicates the free state, and a value greater than 0 indicates the shared read state. std::atomic_int lockCount_; - // Thread counter waiting for write lock + // Thread counter waiting for the write lock. std::atomic_uint writeWaitCount_; }; /** * @brief UniqueWriteGuard object controls the ownership of a lockable object * within a scope, and is used only as acquisition - * and release of "write locks". + * and release of write locks. * It is actually an encapsulation of the RWLock class, which can be locked * at construction time and unlocked during destruction, * providing a convenient RAII mechanism. @@ -141,8 +142,8 @@ private: /** * @brief UniqueWriteGuard object controls the ownership of a lockable object * within a scope, and is used only as acquisition - * and release of "read locks". - * It is actually a encapsulation of the RWLock class, which can be locked + * and release of read locks. + * It is actually an encapsulation of the RWLock class, which can be locked * at construction time and unlocked during destruction, * providing a convenient RAII mechanism. */ diff --git a/base/include/string_ex.h b/base/include/string_ex.h index f7671d6..cf99110 100644 --- a/base/include/string_ex.h +++ b/base/include/string_ex.h @@ -16,13 +16,13 @@ /** * @file string_ex.h * -* @brief Provide global string operation function implemented in c_utils. +* @brief Provides the global string operation function implemented in c_utils. */ /** * @defgroup StringOperation * @{ -* @brief To operate strings. +* @brief Provides interfaces for operating strings. * * Include converting between uppercase and lowercase, * string replacement, trim and split etc. @@ -37,76 +37,76 @@ namespace OHOS { /** * @ingroup StringOperation - * @brief Convert all letters of string to uppercase. + * @brief Converts all letters in a string to uppercase. * - * @param str Base string. - * @return Return a new converted `std::string` object. + * @param str Indicates the base string. + * @return Returns a new `std::string` object after conversion. */ std::string UpperStr(const std::string& str); /** * @ingroup StringOperation - * @brief Convert all letters of string to lowercase. + * @brief Converts all letters in a string to lowercase. * - * @param str Base string. - * @return Return a new converted `std::string` object. + * @param str Indicates the base string. + * @return Returns a new `std::string` object after conversion. */ std::string LowerStr(const std::string& str); /** * @ingroup StringOperation - * @brief Replace `src` with `dst` in base string `str`. + * @brief Replaces a substring in the base string. * - * @param str Target sub-string to be replaced. - * @param src Base string. - * @param dst Expected sub-string for replacement. - * @return Return a new replaced `std::string` object. + * @param str Indicates the substring to be replaced. + * @param src Indicates the base string. + * @param dst Indicates the expected substring for replacement. + * @return Returns a new `std::string` object after replacement. */ std::string ReplaceStr(const std::string& str, const std::string& src, const std::string& dst); /** * @ingroup StringOperation - * @brief Trim string by `cTrim` at the front and end of `str`. + * @brief Trims a string indicated by `cTrim` from both ends of the base string. * - * @param str Base string. - * @param cTrim Target string used in trim，which is '' by default. - * @return Return a new trimmed `std::string` object. + * @param str Indicates the base string. + * @param cTrim Indicates the string to trim from the base string, which is '' by default. + * @return Returns a new `std::string` object after trimming. */ std::string TrimStr(const std::string& str, const char cTrim = ' '); /** * @ingroup StringOperation - * @brief Convert decimal to hexadecimal string. + * @brief Converts a decimal value to a hexadecimal string. * - * @param value Target decimal value. - * @param upper Specify if output as uppercase, - * whose value is `true` by default。 - * @return Return a new converted `std::string` object. + * @param value Indicates the decimal value to convert. + * @param upper Specifies whether the output string is in uppercase. + * The default value is `true`. + * @return Returns a new `std::string` object after conversion. */ std::string DexToHexString(int value, bool upper = true); /** * @ingroup StringOperation - * @brief Split string by `sep`. + * @brief Splits a string by `sep`. * - * @param str Base string. - * @param sep Sub-string as separator. - * @param strs `std::vector` object to store the results. - * @param canEmpty Specify if output empty string as results, - * whose value is false by default. - * @param needTrim Specify if need to trim by '', - * whose value is true by default. + * @param str Indicates the base string. + * @param sep Indicates the substring to be used as the separator. + * @param strs Indicates the `std::vector` object to store the results. + * @param canEmpty Specifies whether the output string can be an empty string. + * The default value is `false`. + * @param needTrim Specifies whether to remove whitespace from the output string. + * The default value is `true`. */ void SplitStr(const std::string& str, const std::string& sep, std::vector& strs, bool canEmpty = false, bool needTrim = true); /** * @ingroup StringOperation - * @brief Convert int and double and so on to string. + * @brief Converts a value of int, double, or any other type to a string. * - * @tparam T Specific type of input data. - * @param iValue Input data. - * @return Return a new converted `std::string` object. + * @tparam T Indicates the type of the input data. + * @param iValue Indicates the input data. + * @return Returns a new `std::string` object after conversion. */ template inline std::string ToString(T iValue) @@ -116,120 +116,130 @@ inline std::string ToString(T iValue) /** * @ingroup StringOperation - * @brief Convert string to int. + * @brief Converts a string to an int value. * - * @param str String to be converted. - * @param value Target `int` variable to store the result. - * @return Return true if converting success, false if failed. + * @param str Indicates the string to be converted. + * @param value Indicates the `int` variable to store the result. + * @return Returns `true` if the operation is successful; + * returns `false` otherwise. */ bool StrToInt(const std::string& str, int& value); /** * @ingroup StringOperation - * @brief Judge if all characters of the string are numbers. + * @brief Checks whether all characters in a string are numeric. * - * @param str Base string. - * @return Return true if all are numbers, otherwise false. + * @param str Indicates the base string. + * @return Returns `true` if all characters in the string are numeric; + * returns `false` otherwise. */ bool IsNumericStr(const std::string& str); /** * @ingroup StringOperation - * @brief Judge if all characters of the string are alphabet. + * @brief Checks whether all characters in a string are alphabetic. * - * @param str Base string. - * @return Return true if all are alphabet, otherwise false. + * @param str Indicates the base string. + * @return Returns `true` if all characters in the string are alphabetic; + * returns `false` otherwise. */ bool IsAlphaStr(const std::string& str); /** * @ingroup StringOperation - * @brief Judge if all characters of the string are uppercase. + * @brief Checks whether all characters in a string are in uppercase. * - * @param str Base string. - * @return Return true if all are uppercase, otherwise false. + * @param str Indicates the base string. + * @return Returns `true` if all characters in the string are in uppercase; + * returns `false` otherwise. */ bool IsUpperStr(const std::string& str); /** * @ingroup StringOperation - * @brief Judge if all characters of the string are lowercase. + * @brief Checks whether all characters in a string are in lowercase. * - * @param str Base string. - * @return Return true if all are lowercase, otherwise false. + * @param str Indicates the base string. + * @return Returns `true` if all characters in the string are in lowercase; + * returns `false` otherwise. */ bool IsLowerStr(const std::string& str); /** * @ingroup StringOperation - * @brief Judge if `str` contains the `sub`. + * @brief Checks whether a string contains the specified substring. * - * @param str Base string. - * @param sub Target sub-string. - * @return Return true if contains, otherwise false. + * @param str Indicates the base string. + * @param sub Indicates the substring. + * @return Returns `true` if the string contains the specified substring; + * returns `false` otherwise. */ bool IsSubStr(const std::string& str, const std::string& sub); /** * @ingroup StringOperation - * @brief Get the first sub_str between `left` and `right`. + * @brief Obtains the first substring between the substrings specified + * by `left` and `right`. * - * @param str Base string. - * @param left Specified left string. - * @param right Specified right string. - * @param sub Target `std::string` object to store the result string. - * @return Return the right string pos, if failed return string::npos. + * @param str Indicates the base string. + * @param left Indicates the left string. + * @param right Indicates the right string. + * @param sub Indicates the `std::string` object to store the result string. + * @return Returns `pos` if the operation is successful; + * returns `string::npos` otherwise. */ std::string::size_type GetFirstSubStrBetween(const std::string& str, const std::string& left, const std::string& right, std::string& sub); /** * @ingroup StringOperation - * @brief Get all of the sub strings between `left` and `right`. + * @brief Obtains all of the substrings between the substrings specified + * by `left` and `right`. * - * @param str Base string. - * @param left Specified left string. - * @param right Specified right string. - * @param sub Target `std::vector` object to store all of the result strings. + * @param str Indicates the base string. + * @param left Indicates the left string. + * @param right Indicates the right string. + * @param sub Indicates the `std::vector` object to store all the result strings. */ void GetSubStrBetween(const std::string& str, const std::string& left, const std::string& right, std::vector& sub); /** * @ingroup StringOperation - * @brief Judge if the `first`'s letter is same with `second`. + * @brief Checks whether two strings are equal. * - * @param first First input string. - * @param second Second input string. - * @note Case-insensitive. + * @param first Indicates the first string to check. + * @param second Indicates the second string to check. + * @note The string is case-insensitive. */ bool IsSameTextStr(const std::string& first, const std::string& second); /** * @ingroup StringOperation - * @brief Judge if all of the characters in `str` are ASCII encoded. + * @brief Checks whether all characters in a string are ASCII encoded. * - * @param str Base string. - * @return Return true if all are ASCII encoded, otherwise false. + * @param str Indicates the base string. + * @return Returns `true` if all characters in the string are ASCII encoded; + * returns `false` otherwise. */ bool IsAsciiString(const std::string& str); #ifndef IOS_PLATFORM /** * @ingroup StringOperation - * @brief Convert a string from UTF-16 to UTF-8 encoded. + * @brief Converts a string from UTF-16 to UTF-8 encoded. * - * @param str16 Input `std::u16string` object. - * @return If converting failed, return an empty `std::string` object. + * @param str16 Indicates a `std::u16string` object. + * @return Returns an empty `std::string` object if the operation fails. */ std::string Str16ToStr8(const std::u16string& str16); /** * @ingroup StringOperation - * @brief Convert a string from UTF-8 to UTF-16 encoded. + * @brief Converts a string from UTF-8 to UTF-16 encoded. * - * @param str Input `std::string` object. - * @return If converting failed, return an empty `std::u16string` object. + * @param str Indicates a `std::string` object. + * @return Returns an empty `std::u16string` object if the operation fails. */ std::u16string Str8ToStr16(const std::string& str); #endif diff --git a/base/include/timer.h b/base/include/timer.h index 9d04d7b..acc760b 100644 --- a/base/include/timer.h +++ b/base/include/timer.h @@ -30,22 +30,22 @@ namespace OHOS { namespace Utils { /** - * @brief This is a timer manager. + * @brief Implements a timer manager. * - * After "Timer" started, users can register several timed events, which can be - * continuous or once, to it. Some points need to be noticed:\n - * 1. Timer should be set up(via Setup()) before use, and shutdown + * After a timer is started, users can register several timed events, which + * can be continuous or one-shot, to it. Some points need to be noticed:\n + * 1. A timer must be set up (through Setup()) before use, and be shut down * (via Shutdown()) before its deconstruction.\n - * 2. Timer should be set up first and then shutdown. Avoid delegating them to - * different threads since it may cause multithreading problem.\n - * 3. Set up Timer again would not reset this Timer, but return - * `TIMER_ERR_INVALID_VALUE`. If a reset operation is required, shut Timer down - * first and then set it up.\n - * 4. Parameter in Shutdown() determines whether the thread in Timer would be - * detach or join(True(default) --> join; False --> detach). Detach operation - * would cause possible multithreading problems, thus is not recommended. If a + * 2. A timer must be set up first and then shut down. Avoid delegating a + * timer to different threads. Otherwise, multithreading issues may occur.\n + * 3. Setting up a timer again will not reset the timer, but return + * `TIMER_ERR_INVALID_VALUE`. If a reset operation is required, shut down + * the timer first and then set it up.\n + * 4. The parameter in Shutdown() determines whether the thread in the timer + * will be detached. A detach operation may cause possible + * multithreading problems, and is therefore not recommended. If a * detach operation is required, availability of related objects used in - * `thread_` should be guaranteed. + * `thread_` must be guaranteed. */ class Timer { public: @@ -55,58 +55,61 @@ public: public: /** - * @brief Construct Timer. + * @brief Creates a timer. * - * If performance-sensitive, change "timeoutMs" larger before Setup. - * "timeoutMs" default-value(1000ms), performance-estimate: occupy - * fixed-100us in every default-value(1000ms). + * In performance-sensitive scenarios, set `timeoutMs` to a + * greater value before timer setup based on your timed event setttings. The + * default value is 1000 ms. The timeout event requires 100 us to respond. * - * @param name Name for Timer. It is used as the name of thread in Timer. - * @param timeoutMs Time for waiting timer events. It is an integer in - * [-1, INT32MAX], but -1 and 0 is not recommended. -1 means waiting - * forever(until event-trigger). 0 means no waiting, which occupies too - * much cpu time. others means waiting(until event-trigger). + * @param name Indicates the name of the timer. It is used as the name + * of the thread in the timer. + * @param timeoutMs Indicates the duration for which the timer will wait. + * The value is an integer in [-1, INT32MAX], but `-1` and `0` are not + * recommended. `-1` means to wait indefinitely (until the timed event is + * triggered). `0` means not to wait, which occupies too much CPU time. */ explicit Timer(const std::string& name, int timeoutMs = 1000); virtual ~Timer() {} /** - * @brief Set up "Timer". + * @brief Sets up a timer. * - * Do not set up repeatly before shutdown. + * Do not set up a timer before shutting down the existing one. */ virtual uint32_t Setup(); /** - * @brief Shut down "Timer". + * @brief Shuts down this timer. * - * There are two modes to shut the "Timer" down: blocking and unblocking. - * Blocking mode will shut "Timer" down until all running events in "Timer" - * finished. If "timeoutMs" is set as -1, use unblocking mode to avoid - * deadloop. + * A timer can be shut down in blocking or unblocking mode. In blocking + * mode, the timer will be shut down only after all running events + * in the timer have finished. If `timeoutMs` is set to `-1`, use + * unblocking mode to avoid deadloop. * - * @param useJoin Shutdown mode. true means blocking. false means - * unblocking(not recommended). + * @param useJoin Specifies whether to use blocking mode. The value `true` + * means to use blocking mode, and `false` (not recommended) means + * the opposite. */ virtual void Shutdown(bool useJoin = true); /** - * @brief Regist timed events. + * @brief Registers timed events. * - * @param callback callback function of a timed event. - * @param interval interval time(ms) of a timed event. - * @param once continuity of a timed event. true means discontinuous. false - * means continuous. Default is false. - * @return return ID of a timed event. You can use it as parameter of - * Unregister(). + * @param callback Indicates the callback function of a timed event. + * @param interval Indicates the interval of a timed event, in ms. + * @param once Indicates whether the timed event is one-shot. + * The value `true` means that the timed event is one-shot, + * and `false` means the opposite. The default value is `false`. + * @return Returns the ID of a timed event. You can use it as the + * parameter of Unregister(). * @see Unregister */ uint32_t Register(const TimerCallback& callback, uint32_t interval /* ms */, bool once = false); /** - * @brief Delete a timed events. + * @brief Deletes a timed event. * - * @param timerId ID of the timed event need to be deleted. Users can get - * it by Register(). + * @param timerId Indicates the ID of the timed event to delete. + * It can be obtained through Register(). * @see Register */ void Unregister(uint32_t timerId); @@ -123,7 +126,7 @@ private: private: struct TimerEntry { - uint32_t timerId; // unique id + uint32_t timerId; // Unique ID. uint32_t interval; // million second TimerCallback callback; bool once; -- Gitee