完善双向链表API注释

    百图画鸿蒙 + 百文说内核 + 百万注源码  => 挖透鸿蒙内核源码
    鸿蒙研究站 | http://weharmonyos.com (国内)
              | https://weharmony.github.io (国外)
    oschina | https://my.oschina.net/weharmony
    博客园 | https://www.cnblogs.com/weharmony/
    知乎 | https://www.zhihu.com/people/weharmonyos
    csdn | https://blog.csdn.net/kuangyufei
    51cto | https://harmonyos.51cto.com/column/34
    掘金 | https://juejin.cn/user/756888642000808
    公众号 | 鸿蒙研究站 (weharmonyos)

apps/shell/include/shell_list.h

@@ -357,7 +357,7 @@ static inline void SH_ListHeadInsertList(SH_List *oldList, SH_List *newList)
  * @par Dependency:
  * <ul><li>shell_list.h: the header file that contains the API declaration.</li></ul>
  * @see
- */
+ *///获取指定结构体内的成员相对于结构体起始地址的偏移量
 #define LOS_OFF_SET_OF(type, member) ((uintptr_t)&((type *)0)->member)
 
 /**

kernel/base/core/los_bitmap.c

@@ -122,7 +122,7 @@ VOID LOS_BitmapSetNBits(UINTPTR *bitmap, UINT32 start, UINT32 numsSet)
         *p |= maskToSet;
     }
 }
-///从start位置开始清除numsSet个bit位 置0
+///从start位置开始 清除numsSet个bit位置0 ,对状态字的连续标志位进行清0操作
 VOID LOS_BitmapClrNBits(UINTPTR *bitmap, UINT32 start, UINT32 numsClear)
 {
     UINTPTR *p = bitmap + BITMAP_WORD(start);

kernel/include/los_list.h

@@ -148,7 +148,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListInit(LOS_DL_LIST *list)
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see
- */ 
+ *///判断指定链表节点是否为链表尾端 
 #define LOS_DL_LIST_IS_END(list, node) ((list) == (node) ? TRUE : FALSE)
 
 /**
@@ -170,7 +170,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListInit(LOS_DL_LIST *list)
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see
- */
+ *///判断链表节点是否在双向链表里
 #define LOS_DL_LIST_IS_ON_QUEUE(node) ((node)->pstPrev != NULL && (node)->pstNext != NULL)
 
 /**
@@ -288,7 +288,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListHeadInsert(LOS_DL_LIST *list,
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see LOS_ListAdd
- */
+ *///将指定节点从链表中删除
 LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelete(LOS_DL_LIST *node)
 {
     node->pstNext->pstPrev = node->pstPrev;
@@ -317,7 +317,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelete(LOS_DL_LIST *node)
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see
- */
+ *///判断链表是否为空
 LITE_OS_SEC_ALW_INLINE STATIC INLINE BOOL LOS_ListEmpty(LOS_DL_LIST *list)
 {
     return (BOOL)(list->pstNext == list);
@@ -341,7 +341,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE BOOL LOS_ListEmpty(LOS_DL_LIST *list)
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see LOS_ListDelete
- */
+ *///将指定链表的头端插入到双向链表头端
 LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListAddList(LOS_DL_LIST *oldList, LOS_DL_LIST *newList)
 {
     LOS_DL_LIST *oldListHead = oldList->pstNext;
@@ -446,7 +446,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListHeadInsertList(LOS_DL_LIST *ol
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see
- */
+ *///获取双向链表中第一个链表节点所在的结构体地址，接口的第一个入参表示的是链表中的头节点，第二个入参是要获取的结构体名称，第三个入参是链表在该结构体中的名称
 #define LOS_DL_LIST_ENTRY(item, type, member) \
     ((type *)(VOID *)((CHAR *)(item) - LOS_OFF_SET_OF(type, member)))
 
@@ -470,7 +470,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListHeadInsertList(LOS_DL_LIST *ol
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see
- */
+ *///遍历指定双向链表，获取包含该链表节点的结构体地址
 #define LOS_DL_LIST_FOR_EACH_ENTRY(item, list, type, member)             \
     for (item = LOS_DL_LIST_ENTRY((list)->pstNext, type, member);        \
          &(item)->member != (list);                                      \
@@ -497,7 +497,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListHeadInsertList(LOS_DL_LIST *ol
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see
- */
+ *///遍历指定双向链表，获取包含该链表节点的结构体地址，并存储包含当前节点的后继节点的结构体地址
 #define LOS_DL_LIST_FOR_EACH_ENTRY_SAFE(item, next, list, type, member)               \
     for (item = LOS_DL_LIST_ENTRY((list)->pstNext, type, member),                     \
          next = LOS_DL_LIST_ENTRY((item)->member.pstNext, type, member);              \
@@ -521,7 +521,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListHeadInsertList(LOS_DL_LIST *ol
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see
- */
+ *///将指定节点从链表中删除，并使用该节点初始化链表
 LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelInit(LOS_DL_LIST *list)
 {
     list->pstNext->pstPrev = list->pstPrev;
@@ -547,7 +547,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelInit(LOS_DL_LIST *list)
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see
- */
+ */ //遍历双向链表
 #define LOS_DL_LIST_FOR_EACH(item, list) \
     for (item = (list)->pstNext;         \
          (item) != (list);               \
@@ -572,7 +572,7 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelInit(LOS_DL_LIST *list)
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see
- */
+ *///遍历双向链表，并存储当前节点的后继节点用于安全校验
 #define LOS_DL_LIST_FOR_EACH_SAFE(item, next, list)      \
     for (item = (list)->pstNext, next = (item)->pstNext; \
          (item) != (list);                               \
@@ -595,9 +595,11 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelInit(LOS_DL_LIST *list)
  * @par Dependency:
  * <ul><li>los_list.h: the header file that contains the API declaration.</li></ul>
  * @see
- */
+ *///定义一个节点并初始化为双向链表节点
 #define LOS_DL_LIST_HEAD(list) LOS_DL_LIST list = { &(list), &(list) }
 
+//获取双向链表中第一个链表节点所在的结构体地址，接口的第一个入参表示的是链表中的头节点，
+//第二个入参是要获取的结构体名称，第三个入参是链表在该结构体中的名称。如果链表为空，返回NULL。
 #define LOS_ListPeekHeadType(list, type, element) ({             \
     type *__t;                                                   \
     if ((list)->pstNext == list) {                               \
@@ -608,6 +610,9 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelInit(LOS_DL_LIST *list)
     __t;                                                         \
 })
 
+//获取双向链表中第一个链表节点所在的结构体地址，并把第一个链表节点从链表中删除。
+//接口的第一个入参表示的是链表中的头节点，第二个入参是要获取的结构体名称，
+//第三个入参是链表在该结构体中的名称。如果链表为空，返回NULL。
 #define LOS_ListRemoveHeadType(list, type, element) ({           \
     type *__t;                                                   \
     if ((list)->pstNext == list) {                               \
@@ -619,6 +624,10 @@ LITE_OS_SEC_ALW_INLINE STATIC INLINE VOID LOS_ListDelInit(LOS_DL_LIST *list)
     __t;                                                         \
 })
 
+//获取双向链表中指定链表节点的下一个节点所在的结构体地址。
+//接口的第一个入参表示的是链表中的头节点，第二个入参是指定的链表节点，
+//第三个入参是要获取的结构体名称，第四个入参是链表在该结构体中的名称。
+//如果链表节点下一个为链表头结点为空，返回NULL。
 #define LOS_ListNextType(list, item, type, element) ({           \
     type *__t;                                                   \
     if ((item)->pstNext == list) {                               \

zzz/git/push.sh

 git add -A
-git commit -m  ' Posix | 系统调用 接口注释  
+git commit -m  ' 完善双向链表API注释  
     百图画鸿蒙 + 百文说内核 + 百万注源码  => 挖透鸿蒙内核源码
     鸿蒙研究站 | http://weharmonyos.com (国内) 
               | https://weharmony.github.io (国外)