Commit a34b0e4e authored by Randy Dunlap's avatar Randy Dunlap Committed by Jakub Kicinski
Browse files

net/iucv: clean up iucv kernel-doc warnings 



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: default avatarRandy Dunlap <rdunlap@infradead.org>
Reviewed-by: default avatarAlexandra Winter <wintera@linux.ibm.com>
Link: https://patch.msgid.link/20260203075248.1177869-1-rdunlap@infradead.org


Signed-off-by: default avatarJakub Kicinski <kuba@kernel.org>
parent 42a940ef

include/net/iucv/iucv.h

+3 −204
Original line number Diff line number Diff line
@@ -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);

net/iucv/iucv.c

+108 −119

File changed.

Preview size limit exceeded, changes collapsed.