net/tipc: fix tipc header files for kernel-doc

Fix tipc header files for adding to the networking docbook.

Remove some uses of "/**" that were not kernel-doc notation.

Fix some source formatting to eliminate Sphinx warnings.

Add missing struct member and function argument kernel-doc descriptions.

Correct the description of a couple of struct members that were
marked as "(FIXME)".

Documentation/networking/tipc:18: ../net/tipc/name_table.h:65: WARNING: Unexpected indentation.
Documentation/networking/tipc:18: ../net/tipc/name_table.h:66: WARNING: Block quote ends without a blank line; unexpected unindent.

../net/tipc/bearer.h:128: warning: Function parameter or member 'min_win' not described in 'tipc_media'
../net/tipc/bearer.h:128: warning: Function parameter or member 'max_win' not described in 'tipc_media'

../net/tipc/bearer.h:171: warning: Function parameter or member 'min_win' not described in 'tipc_bearer'
../net/tipc/bearer.h:171: warning: Function parameter or member 'max_win' not described in 'tipc_bearer'
../net/tipc/bearer.h:171: warning: Function parameter or member 'disc' not described in 'tipc_bearer'
../net/tipc/bearer.h:171: warning: Function parameter or member 'up' not described in 'tipc_bearer'
../net/tipc/bearer.h:171: warning: Function parameter or member 'refcnt' not described in 'tipc_bearer'

../net/tipc/name_distr.h:68: warning: Function parameter or member 'port' not described in 'distr_item'

../net/tipc/name_table.h:111: warning: Function parameter or member 'services' not described in 'name_table'
../net/tipc/name_table.h:111: warning: Function parameter or member 'cluster_scope_lock' not described in 'name_table'
../net/tipc/name_table.h:111: warning: Function parameter or member 'rc_dests' not described in 'name_table'
../net/tipc/name_table.h:111: warning: Function parameter or member 'snd_nxt' not described in 'name_table'

../net/tipc/subscr.h:67: warning: Function parameter or member 'kref' not described in 'tipc_subscription'
../net/tipc/subscr.h:67: warning: Function parameter or member 'net' not described in 'tipc_subscription'
../net/tipc/subscr.h:67: warning: Function parameter or member 'service_list' not described in 'tipc_subscription'
../net/tipc/subscr.h:67: warning: Function parameter or member 'conid' not described in 'tipc_subscription'
../net/tipc/subscr.h:67: warning: Function parameter or member 'inactive' not described in 'tipc_subscription'
../net/tipc/subscr.h:67: warning: Function parameter or member 'lock' not described in 'tipc_subscription'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
This commit is contained in:
Randy Dunlap 2020-11-29 10:32:43 -08:00 committed by Jakub Kicinski
parent 7fe2af16e6
commit ff10527e89
5 changed files with 24 additions and 14 deletions

View File

@ -93,7 +93,8 @@ struct tipc_bearer;
* @raw2addr: convert from raw addr format to media addr format * @raw2addr: convert from raw addr format to media addr format
* @priority: default link (and bearer) priority * @priority: default link (and bearer) priority
* @tolerance: default time (in ms) before declaring link failure * @tolerance: default time (in ms) before declaring link failure
* @window: default window (in packets) before declaring link congestion * @min_win: minimum window (in packets) before declaring link congestion
* @max_win: maximum window (in packets) before declaring link congestion
* @mtu: max packet size bearer can support for media type not dependent on * @mtu: max packet size bearer can support for media type not dependent on
* underlying device MTU * underlying device MTU
* @type_id: TIPC media identifier * @type_id: TIPC media identifier
@ -138,12 +139,15 @@ struct tipc_media {
* @pt: packet type for bearer * @pt: packet type for bearer
* @rcu: rcu struct for tipc_bearer * @rcu: rcu struct for tipc_bearer
* @priority: default link priority for bearer * @priority: default link priority for bearer
* @window: default window size for bearer * @min_win: minimum window (in packets) before declaring link congestion
* @max_win: maximum window (in packets) before declaring link congestion
* @tolerance: default link tolerance for bearer * @tolerance: default link tolerance for bearer
* @domain: network domain to which links can be established * @domain: network domain to which links can be established
* @identity: array index of this bearer within TIPC bearer array * @identity: array index of this bearer within TIPC bearer array
* @link_req: ptr to (optional) structure making periodic link setup requests * @disc: ptr to link setup request
* @net_plane: network plane ('A' through 'H') currently associated with bearer * @net_plane: network plane ('A' through 'H') currently associated with bearer
* @up: bearer up flag (bit 0)
* @refcnt: tipc_bearer reference counter
* *
* Note: media-specific code is responsible for initialization of the fields * Note: media-specific code is responsible for initialization of the fields
* indicated below when a bearer is enabled; TIPC's generic bearer code takes * indicated below when a bearer is enabled; TIPC's generic bearer code takes

View File

@ -1,5 +1,5 @@
/* SPDX-License-Identifier: GPL-2.0 */ /* SPDX-License-Identifier: GPL-2.0 */
/** /*
* net/tipc/crypto.h: Include file for TIPC crypto * net/tipc/crypto.h: Include file for TIPC crypto
* *
* Copyright (c) 2019, Ericsson AB * Copyright (c) 2019, Ericsson AB
@ -53,7 +53,7 @@
#define TIPC_AES_GCM_IV_SIZE 12 #define TIPC_AES_GCM_IV_SIZE 12
#define TIPC_AES_GCM_TAG_SIZE 16 #define TIPC_AES_GCM_TAG_SIZE 16
/** /*
* TIPC crypto modes: * TIPC crypto modes:
* - CLUSTER_KEY: * - CLUSTER_KEY:
* One single key is used for both TX & RX in all nodes in the cluster. * One single key is used for both TX & RX in all nodes in the cluster.
@ -69,7 +69,7 @@ enum {
extern int sysctl_tipc_max_tfms __read_mostly; extern int sysctl_tipc_max_tfms __read_mostly;
extern int sysctl_tipc_key_exchange_enabled __read_mostly; extern int sysctl_tipc_key_exchange_enabled __read_mostly;
/** /*
* TIPC encryption message format: * TIPC encryption message format:
* *
* 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0 * 3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0 0

View File

@ -46,7 +46,7 @@
* @type: name sequence type * @type: name sequence type
* @lower: name sequence lower bound * @lower: name sequence lower bound
* @upper: name sequence upper bound * @upper: name sequence upper bound
* @ref: publishing port reference * @port: publishing port reference
* @key: publication key * @key: publication key
* *
* ===> All fields are stored in network byte order. <=== * ===> All fields are stored in network byte order. <===

View File

@ -60,8 +60,8 @@ struct tipc_group;
* @key: publication key, unique across the cluster * @key: publication key, unique across the cluster
* @id: publication id * @id: publication id
* @binding_node: all publications from the same node which bound this one * @binding_node: all publications from the same node which bound this one
* - Remote publications: in node->publ_list * - Remote publications: in node->publ_list;
* Used by node/name distr to withdraw publications when node is lost * Used by node/name distr to withdraw publications when node is lost
* - Local/node scope publications: in name_table->node_scope list * - Local/node scope publications: in name_table->node_scope list
* - Local/cluster scope publications: in name_table->cluster_scope list * - Local/cluster scope publications: in name_table->cluster_scope list
* @binding_sock: all publications from the same socket which bound this one * @binding_sock: all publications from the same socket which bound this one
@ -92,13 +92,16 @@ struct publication {
/** /**
* struct name_table - table containing all existing port name publications * struct name_table - table containing all existing port name publications
* @seq_hlist: name sequence hash lists * @services: name sequence hash lists
* @node_scope: all local publications with node scope * @node_scope: all local publications with node scope
* - used by name_distr during re-init of name table * - used by name_distr during re-init of name table
* @cluster_scope: all local publications with cluster scope * @cluster_scope: all local publications with cluster scope
* - used by name_distr to send bulk updates to new nodes * - used by name_distr to send bulk updates to new nodes
* - used by name_distr during re-init of name table * - used by name_distr during re-init of name table
* @cluster_scope_lock: lock for accessing @cluster_scope
* @local_publ_count: number of publications issued by this node * @local_publ_count: number of publications issued by this node
* @rc_dests: destination node counter
* @snd_nxt: next sequence number to be used
*/ */
struct name_table { struct name_table {
struct hlist_head services[TIPC_NAMETBL_SIZE]; struct hlist_head services[TIPC_NAMETBL_SIZE];

View File

@ -48,12 +48,15 @@ struct tipc_conn;
/** /**
* struct tipc_subscription - TIPC network topology subscription object * struct tipc_subscription - TIPC network topology subscription object
* @subscriber: pointer to its subscriber * @kref: reference count for this subscription
* @seq: name sequence associated with subscription * @net: network namespace associated with subscription
* @timer: timer governing subscription duration (optional) * @timer: timer governing subscription duration (optional)
* @nameseq_list: adjacent subscriptions in name sequence's subscription list * @service_list: adjacent subscriptions in name sequence's subscription list
* @sub_list: adjacent subscriptions in subscriber's subscription list * @sub_list: adjacent subscriptions in subscriber's subscription list
* @evt: template for events generated by subscription * @evt: template for events generated by subscription
* @conid: connection identifier of topology server
* @inactive: true if this subscription is inactive
* @lock: serialize up/down and timer events
*/ */
struct tipc_subscription { struct tipc_subscription {
struct kref kref; struct kref kref;
@ -64,7 +67,7 @@ struct tipc_subscription {
struct tipc_event evt; struct tipc_event evt;
int conid; int conid;
bool inactive; bool inactive;
spinlock_t lock; /* serialize up/down and timer events */ spinlock_t lock;
}; };
struct tipc_subscription *tipc_sub_subscribe(struct net *net, struct tipc_subscription *tipc_sub_subscribe(struct net *net,