linux-bluetooth.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
* [Bluez-devel] [PATCH] l2cap.c: adding some kernel-docs
@ 2006-02-28 13:15 Martin Röhricht
  2006-02-28 14:59 ` [Bluez-devel] rfcomm socket connect timeout Dave Mielke
  0 siblings, 1 reply; 6+ messages in thread
From: Martin Röhricht @ 2006-02-28 13:15 UTC (permalink / raw)
  To: bluez-devel

[-- 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;

^ permalink raw reply	[flat|nested] 6+ messages in thread
end of thread, other threads:[~2006-02-28 16:08 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2006-02-28 13:15 [Bluez-devel] [PATCH] l2cap.c: adding some kernel-docs Martin Röhricht
2006-02-28 14:59 ` [Bluez-devel] rfcomm socket connect timeout Dave Mielke
2006-02-28 15:19   ` Marcel Holtmann
2006-02-28 15:50     ` Dave Mielke
2006-02-28 16:08       ` Marcel Holtmann
2006-02-28 15:23   ` ermal mino

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).