[00/10,net-next] net/tipc: fix all kernel-doc and add TIPC networking chapter

Message

Randy Dunlap Nov. 25, 2020, 4:20 a.m. UTC

Fix lots of net/tipc/ kernel-doc warnings. Add many struct field and
function parameter descriptions.

Then add a TIPC chapter to the networking documentation book.


Note: some of the struct members and function parameters are marked
with "FIXME". They could use some additional descriptions if
someone could help add to them. Thanks.


Question: is net/tipc/discover.c, in tipc_disc_delete() kernel-doc,
what is the word "duest"?  Should it be changed?


Cc: Jon Maloy <[e-mail]>
Cc: Ying Xue <[e-mail]>
Cc: [e-mail]
Cc: [e-mail]
Cc: "David S. Miller" <[e-mail]>
Cc: Jakub Kicinski <[e-mail]>

[PATCH 01/10 net-next] net/tipc: fix tipc header files for kernel-doc
[PATCH 02/10 net-next] net/tipc: fix various kernel-doc warnings
[PATCH 03/10 net-next] net/tipc: fix bearer.c for kernel-doc
[PATCH 04/10 net-next] net/tipc: fix link.c kernel-doc
[PATCH 05/10 net-next] net/tipc: fix name_distr.c kernel-doc
[PATCH 06/10 net-next] net/tipc: fix name_table.c kernel-doc
[PATCH 07/10 net-next] net/tipc: fix node.c kernel-doc
[PATCH 08/10 net-next] net/tipc: fix socket.c kernel-doc
[PATCH 09/10 net-next] net/tipc: fix all function Return: notation
[PATCH 10/10 net-next] net/tipc: add TIPC chapter to networking Documentation


 Documentation/networking/index.rst |    1 
 Documentation/networking/tipc.rst  |  101 +++++++++++++++++++++++++++
 net/tipc/bearer.c                  |   22 +++++
 net/tipc/bearer.h                  |   10 +-
 net/tipc/crypto.c                  |   55 ++++++++------
 net/tipc/crypto.h                  |    6 -
 net/tipc/discover.c                |    3 
 net/tipc/link.c                    |   46 ++++++++++--
 net/tipc/msg.c                     |   29 ++++---
 net/tipc/name_distr.c              |   29 +++++++
 net/tipc/name_distr.h              |    2 
 net/tipc/name_table.c              |   46 +++++++++---
 net/tipc/name_table.h              |    9 +-
 net/tipc/node.c                    |   37 ++++++++-
 net/tipc/socket.c                  |   92 +++++++++++++++---------
 net/tipc/subscr.c                  |    8 +-
 net/tipc/subscr.h                  |   11 +-
 net/tipc/trace.c                   |    2 
 net/tipc/udp_media.c               |    8 +-
 19 files changed, 404 insertions(+), 113 deletions(-)

Comments

Jakub Kicinski Nov. 28, 2020, 1:41 a.m. UTC | #1

On Tue, 24 Nov 2020 20:20:16 -0800 Randy Dunlap wrote:
> Fix lots of net/tipc/ kernel-doc warnings. Add many struct field and
> function parameter descriptions.
> 
> Then add a TIPC chapter to the networking documentation book.
> 
> 
> Note: some of the struct members and function parameters are marked
> with "FIXME". They could use some additional descriptions if
> someone could help add to them. Thanks.
> 
> 
> Question: is net/tipc/discover.c, in tipc_disc_delete() kernel-doc,
> what is the word "duest"?  Should it be changed?

Thanks for cleaning those up! 

Looks like this had a conflict with commits from 6375da9dac8b ("Merge
branch 'tipc-some-minor-improvements'") - please rebase.

Xue, Ying Nov. 29, 2020, 7:37 a.m. UTC | #2

On 11/25/20 12:20 PM, Randy Dunlap wrote:
> 
> Question: is net/tipc/discover.c, in tipc_disc_delete() kernel-doc,
> what is the word "duest"?  Should it be changed?

The "duest" is a typo, and it should be "dest" defined as below:
struct tipc_discoverer {
        u32 bearer_id;
        struct tipc_media_addr dest; ===> "dest"
        struct net *net;
        u32 domain;
        int num_nodes;
        spinlock_t lock;
        struct sk_buff *skb;
        struct timer_list timer;
        unsigned long timer_intv;
};

Randy Dunlap Nov. 29, 2020, 5:54 p.m. UTC | #3

On 11/28/20 11:37 PM, Ying Xue wrote:
> On 11/25/20 12:20 PM, Randy Dunlap wrote:
>>
>> Question: is net/tipc/discover.c, in tipc_disc_delete() kernel-doc,
>> what is the word "duest"?  Should it be changed?
> 
> The "duest" is a typo, and it should be "dest" defined as below:
> struct tipc_discoverer {
>         u32 bearer_id;
>         struct tipc_media_addr dest; ===> "dest"
>         struct net *net;
>         u32 domain;
>         int num_nodes;
>         spinlock_t lock;
>         struct sk_buff *skb;
>         struct timer_list timer;
>         unsigned long timer_intv;
> };
> 

Thanks. I'll take care of this one and your comments
on patch #1.