torvalds/linux
3
0
Fork 0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-03-22 07:27:12 +08:00
Code Issues Packages Projects Releases Wiki Activity

net/iucv: clean up iucv kernel-doc warnings

Browse Source 
Fix numerous (many) kernel-doc warnings in iucv.[ch]:

- convert function documentation comments to a common (kernel-doc) look,
  even for static functions (without "/**")
- use matching parameter and parameter description names
- use better wording in function descriptions (Jakub & AI)
- remove duplicate kernel-doc comments from the header file (Jakub)

Examples:

Warning: include/net/iucv/iucv.h:210 missing initial short description
 on line: * iucv_unregister
Warning: include/net/iucv/iucv.h:216 function parameter 'handle' not
 described in 'iucv_unregister'
Warning: include/net/iucv/iucv.h:467 function parameter 'answer' not
 described in 'iucv_message_send2way'
Warning: net/iucv/iucv.c:727 missing initial short description on line:
 * iucv_cleanup_queue

Build-tested with both "make htmldocs" and "make ARCH=s390 defconfig all".

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Alexandra Winter <wintera@linux.ibm.com>
Link: https://patch.msgid.link/20260203075248.1177869-1-rdunlap@infradead.org
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
This commit is contained in:
Randy Dunlap
2026-02-02 23:52:48 -08:00
committed by Jakub Kicinski
parent 42a940ef18
commit a34b0e4e21
2 changed files with 111 additions and 323 deletions
Download Patch File Download Diff File Expand all files Collapse all files

207
include/net/iucv/iucv.h
View File

@@ -195,35 +195,15 @@ struct iucv_handler {
struct list_head paths;
};
/**
* iucv_register:
* @handler: address of iucv handler structure
* @smp: != 0 indicates that the handler can deal with out of order messages
*
* Registers a driver with IUCV.
*
* Returns: 0 on success, -ENOMEM if the memory allocation for the pathid
* table failed, or -EIO if IUCV_DECLARE_BUFFER failed on all cpus.
*/
int iucv_register(struct iucv_handler *handler, int smp);
void iucv_unregister(struct iucv_handler *handler, int smp);
/**
* iucv_unregister
* @handler: address of iucv handler structure
* @smp: != 0 indicates that the handler can deal with out of order messages
*
* Unregister driver from IUCV.
*/
void iucv_unregister(struct iucv_handler *handle, int smp);
/**
* iucv_path_alloc
* iucv_path_alloc - Allocate a new path structure for use with iucv_connect.
* @msglim: initial message limit
* @flags: initial flags
* @gfp: kmalloc allocation flag
*
* Allocate a new path structure for use with iucv_connect.
*
* Returns: NULL if the memory allocation failed or a pointer to the
* path structure.
*/
@@ -240,229 +220,48 @@ static inline struct iucv_path *iucv_path_alloc(u16 msglim, u8 flags, gfp_t gfp)
}
/**
* iucv_path_free
* iucv_path_free - Frees a path structure.
* @path: address of iucv path structure
*
* Frees a path structure.
*/
static inline void iucv_path_free(struct iucv_path *path)
{
kfree(path);
}
/**
* iucv_path_accept
* @path: address of iucv path structure
* @handler: address of iucv handler structure
* @userdata: 16 bytes of data reflected to the communication partner
* @private: private data passed to interrupt handlers for this path
*
* This function is issued after the user received a connection pending
* external interrupt and now wishes to complete the IUCV communication path.
*
* Returns: the result of the CP IUCV call.
*/
int iucv_path_accept(struct iucv_path *path, struct iucv_handler *handler,
u8 *userdata, void *private);
/**
* iucv_path_connect
* @path: address of iucv path structure
* @handler: address of iucv handler structure
* @userid: 8-byte user identification
* @system: 8-byte target system identification
* @userdata: 16 bytes of data reflected to the communication partner
* @private: private data passed to interrupt handlers for this path
*
* This function establishes an IUCV path. Although the connect may complete
* successfully, you are not able to use the path until you receive an IUCV
* Connection Complete external interrupt.
*
* Returns: the result of the CP IUCV call.
*/
int iucv_path_connect(struct iucv_path *path, struct iucv_handler *handler,
u8 *userid, u8 *system, u8 *userdata,
void *private);
/**
* iucv_path_quiesce:
* @path: address of iucv path structure
* @userdata: 16 bytes of data reflected to the communication partner
*
* This function temporarily suspends incoming messages on an IUCV path.
* You can later reactivate the path by invoking the iucv_resume function.
*
* Returns: the result from the CP IUCV call.
*/
int iucv_path_quiesce(struct iucv_path *path, u8 *userdata);
/**
* iucv_path_resume:
* @path: address of iucv path structure
* @userdata: 16 bytes of data reflected to the communication partner
*
* This function resumes incoming messages on an IUCV path that has
* been stopped with iucv_path_quiesce.
*
* Returns: the result from the CP IUCV call.
*/
int iucv_path_resume(struct iucv_path *path, u8 *userdata);
/**
* iucv_path_sever
* @path: address of iucv path structure
* @userdata: 16 bytes of data reflected to the communication partner
*
* This function terminates an IUCV path.
*
* Returns: the result from the CP IUCV call.
*/
int iucv_path_sever(struct iucv_path *path, u8 *userdata);
/**
* iucv_message_purge
* @path: address of iucv path structure
* @msg: address of iucv msg structure
* @srccls: source class of message
*
* Cancels a message you have sent.
*
* Returns: the result from the CP IUCV call.
*/
int iucv_message_purge(struct iucv_path *path, struct iucv_message *msg,
u32 srccls);
/**
* iucv_message_receive
* @path: address of iucv path structure
* @msg: address of iucv msg structure
* @flags: flags that affect how the message is received (IUCV_IPBUFLST)
* @buffer: address of data buffer or address of struct iucv_array
* @size: length of data buffer
* @residual:
*
* This function receives messages that are being sent to you over
* established paths. This function will deal with RMDATA messages
* embedded in struct iucv_message as well.
*
* Locking: local_bh_enable/local_bh_disable
*
* Returns: the result from the CP IUCV call.
*/
int iucv_message_receive(struct iucv_path *path, struct iucv_message *msg,
u8 flags, void *buffer, size_t size, size_t *residual);
/**
* __iucv_message_receive
* @path: address of iucv path structure
* @msg: address of iucv msg structure
* @flags: flags that affect how the message is received (IUCV_IPBUFLST)
* @buffer: address of data buffer or address of struct iucv_array
* @size: length of data buffer
* @residual:
*
* This function receives messages that are being sent to you over
* established paths. This function will deal with RMDATA messages
* embedded in struct iucv_message as well.
*
* Locking: no locking.
*
* Returns: the result from the CP IUCV call.
*/
int __iucv_message_receive(struct iucv_path *path, struct iucv_message *msg,
u8 flags, void *buffer, size_t size,
size_t *residual);
/**
* iucv_message_reject
* @path: address of iucv path structure
* @msg: address of iucv msg structure
*
* The reject function refuses a specified message. Between the time you
* are notified of a message and the time that you complete the message,
* the message may be rejected.
*
* Returns: the result from the CP IUCV call.
*/
int iucv_message_reject(struct iucv_path *path, struct iucv_message *msg);
/**
* iucv_message_reply
* @path: address of iucv path structure
* @msg: address of iucv msg structure
* @flags: how the reply is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST)
* @reply: address of data buffer or address of struct iucv_array
* @size: length of reply data buffer
*
* This function responds to the two-way messages that you receive. You
* must identify completely the message to which you wish to reply. ie,
* pathid, msgid, and trgcls. Prmmsg signifies the data is moved into
* the parameter list.
*
* Returns: the result from the CP IUCV call.
*/
int iucv_message_reply(struct iucv_path *path, struct iucv_message *msg,
u8 flags, void *reply, size_t size);
/**
* iucv_message_send
* @path: address of iucv path structure
* @msg: address of iucv msg structure
* @flags: how the message is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST)
* @srccls: source class of message
* @buffer: address of data buffer or address of struct iucv_array
* @size: length of send buffer
*
* This function transmits data to another application. Data to be
* transmitted is in a buffer and this is a one-way message and the
* receiver will not reply to the message.
*
* Locking: local_bh_enable/local_bh_disable
*
* Returns: the result from the CP IUCV call.
*/
int iucv_message_send(struct iucv_path *path, struct iucv_message *msg,
u8 flags, u32 srccls, void *buffer, size_t size);
/**
* __iucv_message_send
* @path: address of iucv path structure
* @msg: address of iucv msg structure
* @flags: how the message is sent (IUCV_IPRMDATA, IUCV_IPPRTY, IUCV_IPBUFLST)
* @srccls: source class of message
* @buffer: address of data buffer or address of struct iucv_array
* @size: length of send buffer
*
* This function transmits data to another application. Data to be
* transmitted is in a buffer and this is a one-way message and the
* receiver will not reply to the message.
*
* Locking: no locking.
*
* Returns: the result from the CP IUCV call.
*/
int __iucv_message_send(struct iucv_path *path, struct iucv_message *msg,
u8 flags, u32 srccls, void *buffer, size_t size);
/**
* iucv_message_send2way
* @path: address of iucv path structure
* @msg: address of iucv msg structure
* @flags: how the message is sent and the reply is received
* (IUCV_IPRMDATA, IUCV_IPBUFLST, IUCV_IPPRTY, IUCV_ANSLST)
* @srccls: source class of message
* @buffer: address of data buffer or address of struct iucv_array
* @size: length of send buffer
* @ansbuf: address of answer buffer or address of struct iucv_array
* @asize: size of reply buffer
*
* This function transmits data to another application. Data to be
* transmitted is in a buffer. The receiver of the send is expected to
* reply to the message and a buffer is provided into which IUCV moves
* the reply to this message.
*
* Returns: the result from the CP IUCV call.
*/
int iucv_message_send2way(struct iucv_path *path, struct iucv_message *msg,
u8 flags, u32 srccls, void *buffer, size_t size,
void *answer, size_t asize, size_t *residual);