[Bluez-devel] [PATCH] l2cap.c: adding some kernel-docs

["Martin Röhricht" <ml@felicis.org>]

[-- Attachment #1: Type: text/plain, Size: 851 bytes --]

This small patch adds kernel-docs for four functions in l2cap.c.
Kernel-docs can be used to annotate functions and their parameters like
the following:

/**
 * l2cap_parse_conf_req - parses a conf req packet for options
 * @sk: corresponding socket
 * @data: contains type, length and option data
 * @len: length of the whole configuration request packet
 *
 * Parses a configuration request that may contain multiple
configuration
 * options. Sets the appropriate configuration request parameters from
the
 * remote peer if understood.
 */

One can obtain the information on those annotations in multiple ways,
for example by using the man page style:
  scripts/kernel-doc -man net/bluetooth/l2cap.c | nroff -man | less

I think it's worth the effort for some functions to keep track of the
functionality and the use of different parameters.

Martin

[-- Attachment #2: patch-kernel-doc --]
[-- Type: text/plain, Size: 2157 bytes --]

--- linux-2.6.15-mh2/net/bluetooth/l2cap.c	2006-02-16 11:38:19.000000000 +0100
+++ linux-2.6.15-mr/net/bluetooth/l2cap.c	2006-02-28 14:14:27.000000000 +0100
@@ -1267,6 +1267,16 @@
 	return len;
 }
 
+/**
+ * l2cap_parse_conf_req - parses a conf req packet for options
+ * @sk: corresponding socket
+ * @data: contains type, length and option data
+ * @len: length of the whole configuration request packet
+ *
+ * Parses a configuration request that may contain multiple configuration 
+ * options. Sets the appropriate configuration request parameters from the 
+ * remote peer if understood.
+ */
 static inline void l2cap_parse_conf_req(struct sock *sk, void *data, u16 len)
 {
 	int type, hint, olen; 
@@ -1303,6 +1313,16 @@
 	}
 }
 
+/**
+ * l2cap_add_conf_opt - adds a conf option to a response or a request
+ * @ptr: pointer to complete option
+ * @type: option type (e.g. L2CAP_CONF_MTU)
+ * @len: length of option in Bytes (e.g. MTU == 2, RFC == 9)
+ * @val: contains the data that is being added
+ *
+ * Adds a complete configuration parameter option to a configuration response
+ * or a configuration request.
+ */
 static void l2cap_add_conf_opt(void **ptr, u8 type, u8 len, unsigned long val)
 {
 	struct l2cap_conf_opt *opt = *ptr;
@@ -1333,6 +1353,14 @@
 	*ptr += L2CAP_CONF_OPT_SIZE + len;
 }
 
+/**
+ * l2cap_build_conf_req - Builds a configuration request
+ * @sk: corresponding socket structure
+ * @data: data portion of a conf request packet (dcid, flags, options)
+ * @return: packet length (dcid, flags and options)
+ *
+ * Builds a configuration request with the help of l2cap_add_conf_opt
+ */
 static int l2cap_build_conf_req(struct sock *sk, void *data)
 {
 	struct l2cap_pinfo *pi = l2cap_pi(sk);
@@ -1372,6 +1400,13 @@
 	return result;
 }
 
+/**
+ * l2cap_build_conf_rsp - Builds a configuration response
+ * @sk: corresponding socket structure
+ * @data: data portion of rsp packet (scid, flags, result, config)
+ * @result: result code for response (success/reject/failure/...)
+ * @return: command length
+ */
 static int l2cap_build_conf_rsp(struct sock *sk, void *data, int *result)
 {
 	struct l2cap_conf_rsp *rsp = data;