[PATCH] DocBook: changes and extensions to the kernel documentation

I have recompiled Linux kernel 2.6.11.5 documentation for me and our
university students again.  The documentation could be extended for more
sources which are equipped by structured comments for recent 2.6 kernels.  I
have tried to proceed with that task.  I have done that more times from 2.6.0
time and it gets boring to do same changes again and again.  Linux kernel
compiles after changes for i386 and ARM targets.  I have added references to
some more files into kernel-api book, I have added some section names as well.
 So please, check that changes do not break something and that categories are
not too much skewed.

I have changed kernel-doc to accept "fastcall" and "asmlinkage" words reserved
by kernel convention.  Most of the other changes are modifications in the
comments to make kernel-doc happy, accept some parameters description and do
not bail out on errors.  Changed <pid> to @pid in the description, moved some
#ifdef before comments to correct function to comments bindings, etc.

You can see result of the modified documentation build at
  http://cmp.felk.cvut.cz/~pisa/linux/lkdb-2.6.11.tar.gz

Some more sources are ready to be included into kernel-doc generated
documentation.  Sources has been added into kernel-api for now.  Some more
section names added and probably some more chaos introduced as result of quick
cleanup work.

Signed-off-by: Pavel Pisa <pisa@cmp.felk.cvut.cz>
Signed-off-by: Martin Waitz <tali@admingilde.org>
Signed-off-by: Andrew Morton <akpm@osdl.org>
Signed-off-by: Linus Torvalds <torvalds@osdl.org>

1 files changed, 67 insertions, 67 deletions

diff --git a/include/net/sock.h b/include/net/sock.h
index be81cabd0da3..5bc180adfb14 100644
--- a/include/net/sock.h
+++ b/include/net/sock.h
@@ -90,17 +90,17 @@ do {	spin_lock_init(&((__sk)->sk_lock.slock)); \
 struct sock;
 
 /**
-  *     struct sock_common - minimal network layer representation of sockets
-  *     @skc_family - network address family
-  *     @skc_state - Connection state
-  *     @skc_reuse - %SO_REUSEADDR setting
-  *     @skc_bound_dev_if - bound device index if != 0
-  *     @skc_node - main hash linkage for various protocol lookup tables
-  *     @skc_bind_node - bind hash linkage for various protocol lookup tables
-  *     @skc_refcnt - reference count
-  *
-  *     This is the minimal network layer representation of sockets, the header
-  *     for struct sock and struct tcp_tw_bucket.
+ *      struct sock_common - minimal network layer representation of sockets
+ *      @skc_family: network address family
+ *      @skc_state: Connection state
+ *      @skc_reuse: %SO_REUSEADDR setting
+ *      @skc_bound_dev_if: bound device index if != 0
+ *      @skc_node: main hash linkage for various protocol lookup tables
+ *      @skc_bind_node: bind hash linkage for various protocol lookup tables
+ *      @skc_refcnt: reference count
+ *
+ *      This is the minimal network layer representation of sockets, the header
+ *      for struct sock and struct tcp_tw_bucket.
   */
 struct sock_common {
         unsigned short          skc_family;
@@ -114,60 +114,60 @@ struct sock_common {
 
 /**
   *     struct sock - network layer representation of sockets
-  *     @__sk_common - shared layout with tcp_tw_bucket
-  *     @sk_shutdown - mask of %SEND_SHUTDOWN and/or %RCV_SHUTDOWN
-  *     @sk_userlocks - %SO_SNDBUF and %SO_RCVBUF settings
-  *     @sk_lock -      synchronizer
-  *     @sk_rcvbuf - size of receive buffer in bytes
-  *     @sk_sleep - sock wait queue
-  *     @sk_dst_cache - destination cache
-  *     @sk_dst_lock - destination cache lock
-  *     @sk_policy - flow policy
-  *     @sk_rmem_alloc - receive queue bytes committed
-  *     @sk_receive_queue - incoming packets
-  *     @sk_wmem_alloc - transmit queue bytes committed
-  *     @sk_write_queue - Packet sending queue
-  *     @sk_omem_alloc - "o" is "option" or "other"
-  *     @sk_wmem_queued - persistent queue size
-  *     @sk_forward_alloc - space allocated forward
-  *     @sk_allocation - allocation mode
-  *     @sk_sndbuf - size of send buffer in bytes
-  *     @sk_flags - %SO_LINGER (l_onoff), %SO_BROADCAST, %SO_KEEPALIVE, %SO_OOBINLINE settings
-  *     @sk_no_check - %SO_NO_CHECK setting, wether or not checkup packets
-  *     @sk_route_caps - route capabilities (e.g. %NETIF_F_TSO)
-  *     @sk_lingertime - %SO_LINGER l_linger setting
-  *     @sk_hashent - hash entry in several tables (e.g. tcp_ehash)
-  *     @sk_backlog - always used with the per-socket spinlock held
-  *     @sk_callback_lock - used with the callbacks in the end of this struct
-  *     @sk_error_queue - rarely used
-  *     @sk_prot - protocol handlers inside a network family
-  *     @sk_err - last error
-  *     @sk_err_soft - errors that don't cause failure but are the cause of a persistent failure not just 'timed out'
-  *     @sk_ack_backlog - current listen backlog
-  *     @sk_max_ack_backlog - listen backlog set in listen()
-  *     @sk_priority - %SO_PRIORITY setting
-  *     @sk_type - socket type (%SOCK_STREAM, etc)
-  *     @sk_protocol - which protocol this socket belongs in this network family
-  *     @sk_peercred - %SO_PEERCRED setting
-  *     @sk_rcvlowat - %SO_RCVLOWAT setting
-  *     @sk_rcvtimeo - %SO_RCVTIMEO setting
-  *     @sk_sndtimeo - %SO_SNDTIMEO setting
-  *     @sk_filter - socket filtering instructions
-  *     @sk_protinfo - private area, net family specific, when not using slab
-  *     @sk_timer - sock cleanup timer
-  *     @sk_stamp - time stamp of last packet received
-  *     @sk_socket - Identd and reporting IO signals
-  *     @sk_user_data - RPC layer private data
-  *     @sk_sndmsg_page - cached page for sendmsg
-  *     @sk_sndmsg_off - cached offset for sendmsg
-  *     @sk_send_head - front of stuff to transmit
-  *     @sk_write_pending - a write to stream socket waits to start
-  *     @sk_state_change - callback to indicate change in the state of the sock
-  *     @sk_data_ready - callback to indicate there is data to be processed
-  *     @sk_write_space - callback to indicate there is bf sending space available
-  *     @sk_error_report - callback to indicate errors (e.g. %MSG_ERRQUEUE)
-  *     @sk_backlog_rcv - callback to process the backlog
-  *     @sk_destruct - called at sock freeing time, i.e. when all refcnt == 0
+  *     @__sk_common: shared layout with tcp_tw_bucket
+  *     @sk_shutdown: mask of %SEND_SHUTDOWN and/or %RCV_SHUTDOWN
+  *     @sk_userlocks: %SO_SNDBUF and %SO_RCVBUF settings
+  *     @sk_lock:       synchronizer
+  *     @sk_rcvbuf: size of receive buffer in bytes
+  *     @sk_sleep: sock wait queue
+  *     @sk_dst_cache: destination cache
+  *     @sk_dst_lock: destination cache lock
+  *     @sk_policy: flow policy
+  *     @sk_rmem_alloc: receive queue bytes committed
+  *     @sk_receive_queue: incoming packets
+  *     @sk_wmem_alloc: transmit queue bytes committed
+  *     @sk_write_queue: Packet sending queue
+  *     @sk_omem_alloc: "o" is "option" or "other"
+  *     @sk_wmem_queued: persistent queue size
+  *     @sk_forward_alloc: space allocated forward
+  *     @sk_allocation: allocation mode
+  *     @sk_sndbuf: size of send buffer in bytes
+  *     @sk_flags: %SO_LINGER (l_onoff), %SO_BROADCAST, %SO_KEEPALIVE, %SO_OOBINLINE settings
+  *     @sk_no_check: %SO_NO_CHECK setting, wether or not checkup packets
+  *     @sk_route_caps: route capabilities (e.g. %NETIF_F_TSO)
+  *     @sk_lingertime: %SO_LINGER l_linger setting
+  *     @sk_hashent: hash entry in several tables (e.g. tcp_ehash)
+  *     @sk_backlog: always used with the per-socket spinlock held
+  *     @sk_callback_lock: used with the callbacks in the end of this struct
+  *     @sk_error_queue: rarely used
+  *     @sk_prot: protocol handlers inside a network family
+  *     @sk_err: last error
+  *     @sk_err_soft: errors that don't cause failure but are the cause of a persistent failure not just 'timed out'
+  *     @sk_ack_backlog: current listen backlog
+  *     @sk_max_ack_backlog: listen backlog set in listen()
+  *     @sk_priority: %SO_PRIORITY setting
+  *     @sk_type: socket type (%SOCK_STREAM, etc)
+  *     @sk_protocol: which protocol this socket belongs in this network family
+  *     @sk_peercred: %SO_PEERCRED setting
+  *     @sk_rcvlowat: %SO_RCVLOWAT setting
+  *     @sk_rcvtimeo: %SO_RCVTIMEO setting
+  *     @sk_sndtimeo: %SO_SNDTIMEO setting
+  *     @sk_filter: socket filtering instructions
+  *     @sk_protinfo: private area, net family specific, when not using slab
+  *     @sk_timer: sock cleanup timer
+  *     @sk_stamp: time stamp of last packet received
+  *     @sk_socket: Identd and reporting IO signals
+  *     @sk_user_data: RPC layer private data
+  *     @sk_sndmsg_page: cached page for sendmsg
+  *     @sk_sndmsg_off: cached offset for sendmsg
+  *     @sk_send_head: front of stuff to transmit
+  *     @sk_write_pending: a write to stream socket waits to start
+  *     @sk_state_change: callback to indicate change in the state of the sock
+  *     @sk_data_ready: callback to indicate there is data to be processed
+  *     @sk_write_space: callback to indicate there is bf sending space available
+  *     @sk_error_report: callback to indicate errors (e.g. %MSG_ERRQUEUE)
+  *     @sk_backlog_rcv: callback to process the backlog
+  *     @sk_destruct: called at sock freeing time, i.e. when all refcnt == 0
  */
 struct sock {
         /*
@@ -1223,8 +1223,8 @@ sock_recv_timestamp(struct msghdr *msg, struct sock *sk, struct sk_buff *skb)
 
 /**
  * sk_eat_skb - Release a skb if it is no longer needed
- * @sk - socket to eat this skb from
- * @skb - socket buffer to eat
+ * @sk: socket to eat this skb from
+ * @skb: socket buffer to eat
  *
  * This routine must be called with interrupts disabled or with the socket
  * locked so that the sk_buff queue operation is ok.