Change in libosmocore[master]: core/linuxlist.h: fix and unify Doxygen documentation

2019-03-27 Thread Harald Welte 
Harald Welte has submitted this change and it was merged. ( 
https://gerrit.osmocom.org/13398 )

Change subject: core/linuxlist.h: fix and unify Doxygen documentation
..

core/linuxlist.h: fix and unify Doxygen documentation

  - drop incorrect \ref and \a references;
  - add missing documentation to LLIST_HEAD_INIT;
  - document parameter 'member' of llist_entry();
  - turn @argument naming into a valid \param format;
  - fix 'type *' vs llist_head loop counter confusion;
  - capitalize and dot-terminate all sentences.

Change-Id: Iac67bdb9d5fbf7c222d04858967337f2428d6a94
---
M include/osmocom/core/linuxlist.h
1 file changed, 96 insertions(+), 99 deletions(-)

Approvals:
  Jenkins Builder: Verified
  Pau Espin Pedrol: Looks good to me, approved
  Harald Welte: Looks good to me, approved



diff --git a/include/osmocom/core/linuxlist.h b/include/osmocom/core/linuxlist.h
index 7791310..d040d90 100644
--- a/include/osmocom/core/linuxlist.h
+++ b/include/osmocom/core/linuxlist.h
@@ -23,11 +23,10 @@

 static inline void prefetch(const void *x) {;}

-/*! cast a member of a structure out to the containing structure
- *
- * \param[in] ptr the pointer to the member.
- * \param[in] type the type of the container struct this is embedded in.
- * \param[in] member the name of the member within the struct.
+/*! Cast a member of a structure out to the containing structure.
+ *  \param[in] ptrthe pointer to the member.
+ *  \param[in] type   the type of the container struct this is embedded in.
+ *  \param[in] member the name of the member within the struct.
  */
 #define container_of(ptr, type, member) ({ \
 const typeof( ((type *)0)->member ) *__mptr = (ptr);   \
@@ -48,22 +47,26 @@
struct llist_head *next, *prev;
 };

+/*! Define a new llist_head pointing to a given llist_head.
+ *  \param[in] name another llist_head to be pointed.
+ */
 #define LLIST_HEAD_INIT(name) { &(name), &(name) }

-/*! define a statically-initialized \ref llist_head
- *  \param[in] name Variable name
- *
- * This is a helper macro that will define a named variable of type
- * \ref llist_head and initialize it */
+/*! Define a statically-initialized variable of type llist_head.
+ *  \param[in] name variable (symbol) name.
+ */
 #define LLIST_HEAD(name) \
struct llist_head name = LLIST_HEAD_INIT(name)

-/*! initialize a \ref llist_head to point back to self */
+/*! Initialize a llist_head to point back to itself.
+ *  \param[in] ptr llist_head to be initialized.
+ */
 #define INIT_LLIST_HEAD(ptr) do { \
(ptr)->next = (ptr); (ptr)->prev = (ptr); \
 } while (0)

-/*! Insert a new entry between two known consecutive entries.
+/*
+ * Insert a new entry between two known consecutive entries.
  *
  * This is only for internal llist manipulation where we know
  * the prev/next entries already!
@@ -78,9 +81,9 @@
prev->next = _new;
 }

-/*! add a new entry into a linked list (at head)
- *  \param _new New entry to be added
- *  \param head \ref llist_head to add it after
+/*! Add a new entry into a linked list (at head).
+ *  \param _new the entry to be added.
+ *  \param head llist_head to prepend the element to.
  *
  * Insert a new entry after the specified head.
  * This is good for implementing stacks.
@@ -90,9 +93,9 @@
__llist_add(_new, head, head->next);
 }

-/*! add a new entry into a linked list (at tail)
- *  \param _new  New entry to be added
- *  \param head  Head of linked list to whose tail we shall add \a _new
+/*! Add a new entry into a linked list (at tail).
+ *  \param _new the entry to be added.
+ *  \param head llist_head to append the element to.
  *
  * Insert a new entry before the specified head.
  * This is useful for implementing queues.
@@ -115,8 +118,8 @@
prev->next = next;
 }

-/*! Delete entry from linked list
- *  \param entry  The element to delete from the llist
+/*! Delete a single entry from a linked list.
+ *  \param entry the element to delete.
  *
  * Note: llist_empty on entry does not return true after this, the entry is
  * in an undefined state.
@@ -128,8 +131,8 @@
entry->prev = (struct llist_head *)LLIST_POISON2;
 }

-/*! Delete entry from linked list and reinitialize it
- *  \param entry  The element to delete from the list
+/*! Delete a single entry from a linked list and reinitialize it.
+ *  \param entry the element to delete and reinitialize.
  */
 static inline void llist_del_init(struct llist_head *entry)
 {
@@ -137,9 +140,9 @@
INIT_LLIST_HEAD(entry);
 }

-/*! Delete from one llist and add as another's head
- *  \param llist The entry to move
- *  \param headThe head that will precede our entry
+/*! Delete from one llist and add as another's head.
+ *  \param llist the entry to move.
+ *  \param head  the head that will precede our entry.
  */
 static inline void llist_move(struct llist_head *llist, struct llist_head 
*head)
 {
@@

Change in libosmocore[master]: core/linuxlist.h: fix and unify Doxygen documentation

2019-03-27 Thread Harald Welte 
Harald Welte has posted comments on this change. ( 
https://gerrit.osmocom.org/13398 )

Change subject: core/linuxlist.h: fix and unify Doxygen documentation
..


Patch Set 2: Code-Review+2


--
To view, visit https://gerrit.osmocom.org/13398
To unsubscribe, or for help writing mail filters, visit 
https://gerrit.osmocom.org/settings

Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-MessageType: comment
Gerrit-Change-Id: Iac67bdb9d5fbf7c222d04858967337f2428d6a94
Gerrit-Change-Number: 13398
Gerrit-PatchSet: 2
Gerrit-Owner: Vadim Yanitskiy 
Gerrit-Reviewer: Harald Welte 
Gerrit-Reviewer: Jenkins Builder (102)
Gerrit-Reviewer: Pau Espin Pedrol 
Gerrit-Reviewer: Vadim Yanitskiy 
Gerrit-Comment-Date: Wed, 27 Mar 2019 07:51:09 +
Gerrit-HasComments: No
Gerrit-HasLabels: Yes

Change in libosmocore[master]: core/linuxlist.h: fix and unify Doxygen documentation

2019-03-25 Thread Pau Espin Pedrol 
Pau Espin Pedrol has posted comments on this change. ( 
https://gerrit.osmocom.org/13398 )

Change subject: core/linuxlist.h: fix and unify Doxygen documentation
..


Patch Set 2: Code-Review+2


--
To view, visit https://gerrit.osmocom.org/13398
To unsubscribe, or for help writing mail filters, visit 
https://gerrit.osmocom.org/settings

Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-MessageType: comment
Gerrit-Change-Id: Iac67bdb9d5fbf7c222d04858967337f2428d6a94
Gerrit-Change-Number: 13398
Gerrit-PatchSet: 2
Gerrit-Owner: Vadim Yanitskiy 
Gerrit-Reviewer: Harald Welte 
Gerrit-Reviewer: Jenkins Builder (102)
Gerrit-Reviewer: Pau Espin Pedrol 
Gerrit-Reviewer: Vadim Yanitskiy 
Gerrit-Comment-Date: Mon, 25 Mar 2019 15:08:23 +
Gerrit-HasComments: No
Gerrit-HasLabels: Yes

Change in libosmocore[master]: core/linuxlist.h: fix and unify Doxygen documentation

2019-03-25 Thread Vadim Yanitskiy 
Hello Harald Welte, Jenkins Builder,

I'd like you to reexamine a change. Please visit

https://gerrit.osmocom.org/13398

to look at the new patch set (#2).

Change subject: core/linuxlist.h: fix and unify Doxygen documentation
..

core/linuxlist.h: fix and unify Doxygen documentation

  - drop incorrect \ref and \a references;
  - add missing documentation to LLIST_HEAD_INIT;
  - document parameter 'member' of llist_entry();
  - turn @argument naming into a valid \param format;
  - fix 'type *' vs llist_head loop counter confusion;
  - capitalize and dot-terminate all sentences.

Change-Id: Iac67bdb9d5fbf7c222d04858967337f2428d6a94
---
M include/osmocom/core/linuxlist.h
1 file changed, 96 insertions(+), 99 deletions(-)


  git pull ssh://gerrit.osmocom.org:29418/libosmocore refs/changes/98/13398/2
--
To view, visit https://gerrit.osmocom.org/13398
To unsubscribe, or for help writing mail filters, visit 
https://gerrit.osmocom.org/settings

Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-MessageType: newpatchset
Gerrit-Change-Id: Iac67bdb9d5fbf7c222d04858967337f2428d6a94
Gerrit-Change-Number: 13398
Gerrit-PatchSet: 2
Gerrit-Owner: Vadim Yanitskiy 
Gerrit-Reviewer: Harald Welte 
Gerrit-Reviewer: Jenkins Builder (102)
Gerrit-Reviewer: Vadim Yanitskiy 
Gerrit-CC: Pau Espin Pedrol

Change in libosmocore[master]: core/linuxlist.h: fix and unify Doxygen documentation

2019-03-25 Thread Vadim Yanitskiy 
Vadim Yanitskiy has posted comments on this change. ( 
https://gerrit.osmocom.org/13398 )

Change subject: core/linuxlist.h: fix and unify Doxygen documentation
..


Patch Set 1:

(4 comments)

https://gerrit.osmocom.org/#/c/13398/1/include/osmocom/core/linuxlist.h
File include/osmocom/core/linuxlist.h:

https://gerrit.osmocom.org/#/c/13398/1/include/osmocom/core/linuxlist.h@50
PS1, Line 50: /*! Define a new llist_head pointing to another llist_head.
> another is confusing here, specially because immediatelly afterwards it' used 
> to point to itself in  […]
Agree, done.


https://gerrit.osmocom.org/#/c/13398/1/include/osmocom/core/linuxlist.h@69
PS1, Line 69:  * Insert a new entry between two known consecutive entries.
> No need for extra line. You can start it with "/*! Insert", see functions 
> below.
This is an internal function, so we probably don't need to have any Doxygen 
documentation for it. I just made it look similar to __llist_del's 
documentation.


https://gerrit.osmocom.org/#/c/13398/1/include/osmocom/core/linuxlist.h@85
PS1, Line 85:  *  \param _new a new entry to be added.
> "the entry to be added".
Done


https://gerrit.osmocom.org/#/c/13398/1/include/osmocom/core/linuxlist.h@86
PS1, Line 86:  *  \param head head of linked list to add it after.
> "add it after" is quite misleading here. […]
Done



--
To view, visit https://gerrit.osmocom.org/13398
To unsubscribe, or for help writing mail filters, visit 
https://gerrit.osmocom.org/settings

Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-MessageType: comment
Gerrit-Change-Id: Iac67bdb9d5fbf7c222d04858967337f2428d6a94
Gerrit-Change-Number: 13398
Gerrit-PatchSet: 1
Gerrit-Owner: Vadim Yanitskiy 
Gerrit-Reviewer: Harald Welte 
Gerrit-Reviewer: Jenkins Builder (102)
Gerrit-Reviewer: Vadim Yanitskiy 
Gerrit-CC: Pau Espin Pedrol 
Gerrit-Comment-Date: Mon, 25 Mar 2019 15:06:58 +
Gerrit-HasComments: Yes
Gerrit-HasLabels: No

Change in libosmocore[master]: core/linuxlist.h: fix and unify Doxygen documentation

2019-03-25 Thread Pau Espin Pedrol 
Pau Espin Pedrol has posted comments on this change. ( 
https://gerrit.osmocom.org/13398 )

Change subject: core/linuxlist.h: fix and unify Doxygen documentation
..


Patch Set 1:

(5 comments)

https://gerrit.osmocom.org/#/c/13398/1/include/osmocom/core/linuxlist.h
File include/osmocom/core/linuxlist.h:

https://gerrit.osmocom.org/#/c/13398/1/include/osmocom/core/linuxlist.h@50
PS1, Line 50: /*! Define a new llist_head pointing to another llist_head.
another is confusing here, specially because immediatelly afterwards it' used 
to point to itself in LLIST_HEAD. So better use "a given" instead of "other".


https://gerrit.osmocom.org/#/c/13398/1/include/osmocom/core/linuxlist.h@69
PS1, Line 69:  * Insert a new entry between two known consecutive entries.
No need for extra line. You can start it with "/*! Insert", see functions below.


https://gerrit.osmocom.org/#/c/13398/1/include/osmocom/core/linuxlist.h@85
PS1, Line 85:  *  \param _new a new entry to be added.
"the entry to be added".


https://gerrit.osmocom.org/#/c/13398/1/include/osmocom/core/linuxlist.h@86
PS1, Line 86:  *  \param head head of linked list to add it after.
"add it after" is quite misleading here. Would be a lot clearer saying " linked 
list head to prepend the element to". I see nowhere the word "prepend" being 
used, and imho it's the one really explaining in an easy way what this function 
does.


https://gerrit.osmocom.org/#/c/13398/1/include/osmocom/core/linuxlist.h@344
PS1, Line 344:
whitespace, we can remove it in this commit or add an extra one.



--
To view, visit https://gerrit.osmocom.org/13398
To unsubscribe, or for help writing mail filters, visit 
https://gerrit.osmocom.org/settings

Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-MessageType: comment
Gerrit-Change-Id: Iac67bdb9d5fbf7c222d04858967337f2428d6a94
Gerrit-Change-Number: 13398
Gerrit-PatchSet: 1
Gerrit-Owner: Vadim Yanitskiy 
Gerrit-Reviewer: Harald Welte 
Gerrit-Reviewer: Jenkins Builder (102)
Gerrit-CC: Pau Espin Pedrol 
Gerrit-Comment-Date: Mon, 25 Mar 2019 14:50:46 +
Gerrit-HasComments: Yes
Gerrit-HasLabels: No

Change in libosmocore[master]: core/linuxlist.h: fix and unify Doxygen documentation

2019-03-25 Thread Vadim Yanitskiy 
Vadim Yanitskiy has uploaded this change for review. ( 
https://gerrit.osmocom.org/13398


Change subject: core/linuxlist.h: fix and unify Doxygen documentation
..

core/linuxlist.h: fix and unify Doxygen documentation

  - drop incorrect \ref and \a references;
  - add missing documentation to LLIST_HEAD_INIT;
  - document parameter 'member' of llist_entry();
  - turn @argument naming into a valid \param format;
  - fix 'type *' vs llist_head loop counter confusion;
  - Capitalize and dot-terminate all sentences.

Change-Id: Iac67bdb9d5fbf7c222d04858967337f2428d6a94
---
M include/osmocom/core/linuxlist.h
1 file changed, 96 insertions(+), 99 deletions(-)



  git pull ssh://gerrit.osmocom.org:29418/libosmocore refs/changes/98/13398/1

diff --git a/include/osmocom/core/linuxlist.h b/include/osmocom/core/linuxlist.h
index 7791310..6d263a4 100644
--- a/include/osmocom/core/linuxlist.h
+++ b/include/osmocom/core/linuxlist.h
@@ -23,11 +23,10 @@

 static inline void prefetch(const void *x) {;}

-/*! cast a member of a structure out to the containing structure
- *
- * \param[in] ptr the pointer to the member.
- * \param[in] type the type of the container struct this is embedded in.
- * \param[in] member the name of the member within the struct.
+/*! Cast a member of a structure out to the containing structure.
+ *  \param[in] ptrthe pointer to the member.
+ *  \param[in] type   the type of the container struct this is embedded in.
+ *  \param[in] member the name of the member within the struct.
  */
 #define container_of(ptr, type, member) ({ \
 const typeof( ((type *)0)->member ) *__mptr = (ptr);   \
@@ -48,22 +47,26 @@
struct llist_head *next, *prev;
 };

+/*! Define a new llist_head pointing to another llist_head.
+ *  \param[in] name another llist_head to be pointed.
+ */
 #define LLIST_HEAD_INIT(name) { &(name), &(name) }

-/*! define a statically-initialized \ref llist_head
- *  \param[in] name Variable name
- *
- * This is a helper macro that will define a named variable of type
- * \ref llist_head and initialize it */
+/*! Define a statically-initialized variable of type llist_head.
+ *  \param[in] name variable (symbol) name.
+ */
 #define LLIST_HEAD(name) \
struct llist_head name = LLIST_HEAD_INIT(name)

-/*! initialize a \ref llist_head to point back to self */
+/*! Initialize a llist_head to point back to itself.
+ *  \param[in] ptr llist_head to be initialized.
+ */
 #define INIT_LLIST_HEAD(ptr) do { \
(ptr)->next = (ptr); (ptr)->prev = (ptr); \
 } while (0)

-/*! Insert a new entry between two known consecutive entries.
+/*
+ * Insert a new entry between two known consecutive entries.
  *
  * This is only for internal llist manipulation where we know
  * the prev/next entries already!
@@ -78,9 +81,9 @@
prev->next = _new;
 }

-/*! add a new entry into a linked list (at head)
- *  \param _new New entry to be added
- *  \param head \ref llist_head to add it after
+/*! Add a new entry into a linked list (at head).
+ *  \param _new a new entry to be added.
+ *  \param head head of linked list to add it after.
  *
  * Insert a new entry after the specified head.
  * This is good for implementing stacks.
@@ -90,9 +93,9 @@
__llist_add(_new, head, head->next);
 }

-/*! add a new entry into a linked list (at tail)
- *  \param _new  New entry to be added
- *  \param head  Head of linked list to whose tail we shall add \a _new
+/*! Add a new entry into a linked list (at tail).
+ *  \param _new a new entry to be added.
+ *  \param head head of linked list to whose tail we shall add.
  *
  * Insert a new entry before the specified head.
  * This is useful for implementing queues.
@@ -115,8 +118,8 @@
prev->next = next;
 }

-/*! Delete entry from linked list
- *  \param entry  The element to delete from the llist
+/*! Delete a single entry from a linked list.
+ *  \param entry the element to delete.
  *
  * Note: llist_empty on entry does not return true after this, the entry is
  * in an undefined state.
@@ -128,8 +131,8 @@
entry->prev = (struct llist_head *)LLIST_POISON2;
 }

-/*! Delete entry from linked list and reinitialize it
- *  \param entry  The element to delete from the list
+/*! Delete a single entry from a linked list and reinitialize it.
+ *  \param entry the element to delete and reinitialize.
  */
 static inline void llist_del_init(struct llist_head *entry)
 {
@@ -137,9 +140,9 @@
INIT_LLIST_HEAD(entry);
 }

-/*! Delete from one llist and add as another's head
- *  \param llist The entry to move
- *  \param headThe head that will precede our entry
+/*! Delete from one llist and add as another's head.
+ *  \param llist the entry to move.
+ *  \param head  the head that will precede our entry.
  */
 static inline void llist_move(struct llist_head *llist, struct llist_head 
*head)
 {
@@ -147,9 +150,9 @@
 llist_add(llist,

Change in libosmocore[master]: core/linuxlist.h: fix and unify Doxygen documentation

2019-03-25 Thread Harald Welte 
Harald Welte has posted comments on this change. ( 
https://gerrit.osmocom.org/13398 )

Change subject: core/linuxlist.h: fix and unify Doxygen documentation
..


Patch Set 1: Code-Review+2


--
To view, visit https://gerrit.osmocom.org/13398
To unsubscribe, or for help writing mail filters, visit 
https://gerrit.osmocom.org/settings

Gerrit-Project: libosmocore
Gerrit-Branch: master
Gerrit-MessageType: comment
Gerrit-Change-Id: Iac67bdb9d5fbf7c222d04858967337f2428d6a94
Gerrit-Change-Number: 13398
Gerrit-PatchSet: 1
Gerrit-Owner: Vadim Yanitskiy 
Gerrit-Reviewer: Harald Welte 
Gerrit-Reviewer: Jenkins Builder (102)
Gerrit-Comment-Date: Mon, 25 Mar 2019 14:43:15 +
Gerrit-HasComments: No
Gerrit-HasLabels: Yes