diff --git a/lustre/include/lustre_dlm.h b/lustre/include/lustre_dlm.h
index 27feb6f..8c5553a 100644
--- a/lustre/include/lustre_dlm.h
+++ b/lustre/include/lustre_dlm.h
@@ -34,14 +34,20 @@
  * Lustre is a trademark of Sun Microsystems, Inc.
  */
 
-#ifndef _LUSTRE_DLM_H__
-#define _LUSTRE_DLM_H__
-
-/** \defgroup ldlm ldlm
+/** \defgroup LDLM Lustre Distributed Lock Manager
+ *
+ * Lustre DLM is based on VAX DLM.
+ * It's two main roles are:
+ *   - to provide locking assuring consistency of data on all Lustre nodes
+ *   - to assure a way for clients to cache state protected by a lock by not
+ *     actually releasing the lock.
  *
  * @{
  */
 
+#ifndef _LUSTRE_DLM_H__
+#define _LUSTRE_DLM_H__
+
 #if defined(__linux__)
 #include <linux/lustre_dlm.h>
 #elif defined(__APPLE__)
@@ -73,6 +79,9 @@ struct obd_device;
 #define LDLM_DEFAULT_MAX_ALIVE (cfs_time_seconds(36000))
 #define LDLM_CTIME_AGE_LIMIT (10)
 
+/**
+ * LDLM non-error return states
+ */
 typedef enum {
         ELDLM_OK = 0,
 
@@ -85,6 +94,13 @@ typedef enum {
         ELDLM_BAD_NAMESPACE    = 401
 } ldlm_error_t;
 
+/**
+ * LDLM namespace type.
+ * the "client" type is actually an indication that this is a narrow local view
+ * into complete namespace on the server. Such namespaces cannot make any
+ * decisions about lack of conflicts or do any autonomous lock granting without
+ * first speaking to a server
+ */
 typedef enum {
         LDLM_NAMESPACE_SERVER = 1 << 0,
         LDLM_NAMESPACE_CLIENT = 1 << 1
@@ -92,9 +108,11 @@ typedef enum {
 
 #define LDLM_FL_LOCK_CHANGED   0x000001 /* extent, mode, or resource changed */
 
-/* If the server returns one of these flags, then the lock was put on that list.
+/**
+ * If the server returns one of these flags, then the lock was put on that list.
  * If the client sends one of these flags (during recovery ONLY!), it wants the
- * lock added to the specified list, no questions asked. -p */
+ * lock added to the specified list, no questions asked. -p
+ */
 #define LDLM_FL_BLOCK_GRANTED  0x000002
 #define LDLM_FL_BLOCK_CONV     0x000004
 #define LDLM_FL_BLOCK_WAIT     0x000008
@@ -105,8 +123,10 @@ typedef enum {
 #define LDLM_FL_WAIT_NOREPROC  0x000040 /* not a real flag, not saved in lock */
 #define LDLM_FL_CANCEL         0x000080 /* cancellation callback already run */
 
-/* Lock is being replayed.  This could probably be implied by the fact that one
- * of BLOCK_{GRANTED,CONV,WAIT} is set, but that is pretty dangerous. */
+/**
+ * Lock is being replayed.  This could probably be implied by the fact that one
+ * of BLOCK_{GRANTED,CONV,WAIT} is set, but that is pretty dangerous.
+ */
 #define LDLM_FL_REPLAY         0x000100
 
 #define LDLM_FL_INTENT_ONLY    0x000200 /* don't grant lock, just do intent */
@@ -124,7 +144,7 @@ typedef enum {
 #define LDLM_FL_NO_TIMEOUT     0x020000 /* Blocked by group lock - wait
                                          * indefinitely */
 
-/* file & record locking */
+/** file & record locking */
 #define LDLM_FL_BLOCK_NOWAIT   0x040000 // server told not to wait if blocked
 #define LDLM_FL_TEST_LOCK      0x080000 // return blocking lock
 
@@ -192,7 +212,7 @@ typedef enum {
 /* Flags sent in AST lock_flags to be mapped into the receiving lock. */
 #define LDLM_AST_FLAGS         (LDLM_FL_DISCARD_DATA)
 
-/* 
+/**
  * --------------------------------------------------------------------------
  * NOTE! Starting from this point, that is, LDLM_FL_* flags with values above
  * 0x80000000 will not be sent over the wire.
@@ -200,15 +220,20 @@ typedef enum {
  */
 
 /* Used for marking lock as an target for -EINTR while cp_ast sleep
- * emulation + race with upcoming bl_ast.  */
+ * emulation + race with upcoming bl_ast. 
+ */
 #define LDLM_FL_FAIL_LOC       0x100000000ULL
 
-/* The blocking callback is overloaded to perform two functions.  These flags
+/**
+ * The blocking callback is overloaded to perform two functions.  These flags
  * indicate which operation should be performed. */
 #define LDLM_CB_BLOCKING    1
 #define LDLM_CB_CANCELING   2
 
-/* compatibility matrix */
+/**
+ * compatibility matrix.
+ * Defines what lock modes are compatible with what other lock modes
+ */
 #define LCK_COMPAT_EX  LCK_NL
 #define LCK_COMPAT_PW  (LCK_COMPAT_EX | LCK_CR)
 #define LCK_COMPAT_PR  (LCK_COMPAT_PW | LCK_PR)
@@ -245,8 +270,8 @@ static inline int lockmode_compat(ldlm_mode_t exist_mode, ldlm_mode_t new_mode)
    -
 */
 
-/*
- * Locking rules:
+/**
+ * Locking rules for LDLM:
  *
  * lr_lock
  *
@@ -269,8 +294,18 @@ struct ldlm_lock;
 struct ldlm_resource;
 struct ldlm_namespace;
 
+/**
+ * Operation on ldlm pools.
+ * LDLM pool is a pool of locks in the namespace without any implicitly
+ * specified limits.
+ * Locks in the pool are organized in LRU.
+ * Local memory pressure or server instructions (e.g. mempressure on server)
+ * can trigger freeing of locks from the pool
+ */
 struct ldlm_pool_ops {
+        /** Recalculate pool \param pl usage */
         int (*po_recalc)(struct ldlm_pool *pl);
+        /** Cancel at least \param nr locks from pool \pl */
         int (*po_shrink)(struct ldlm_pool *pl, int nr,
                          unsigned int gfp_mask);
         int (*po_setup)(struct ldlm_pool *pl, int limit);
@@ -296,6 +331,11 @@ struct ldlm_pool_ops {
  */
 #define LDLM_POOL_CLI_DEF_RECALC_PERIOD (10)
 
+/**
+ * LDLM pool structure to track granted locks.
+ * For purposes of determining when to release locks on e.g. memory pressure.
+ * Teh feature is commonly referred to as lru_resize.
+ */
 struct ldlm_pool {
         /**
          * Pool proc directory.
@@ -368,6 +408,14 @@ typedef int (*ldlm_res_policy)(struct ldlm_namespace *, struct ldlm_lock **,
                                void *req_cookie, ldlm_mode_t mode, int flags,
                                void *data);
 
+/**
+ * LVB operations.
+ * LVB is LDLM Value Block. This is a special opaque (to LDLM) value that could
+ * be assotiated with an LDLM lock and transferred from client to server and
+ * back.
+ *
+ * Currently LVBs are used by OSC-OST code to maintain current object size/times
+ */
 struct ldlm_valblock_ops {
         int (*lvbo_init)(struct ldlm_resource *res);
         int (*lvbo_update)(struct ldlm_resource *res,
@@ -375,12 +423,16 @@ struct ldlm_valblock_ops {
                            int increase);
 };
 
+/**
+ * LDLM pools related, type of lock pool n the namespace.
+ * Greedy means release cached locks agressively
+ */
 typedef enum {
         LDLM_NAMESPACE_GREEDY = 1 << 0,
         LDLM_NAMESPACE_MODEST = 1 << 1
 } ldlm_appetite_t;
 
-/*
+/**
  * Default values for the "max_nolock_size", "contention_time" and
  * "contended_locks" namespace tunables.
  */
@@ -388,6 +440,27 @@ typedef enum {
 #define NS_DEFAULT_CONTENTION_SECONDS 2
 #define NS_DEFAULT_CONTENDED_LOCKS 32
 
+/**
+ * LDLM Namespace.
+ *
+ * Namespace serves to contain locks related to particluar service.
+ * There are two kinds of namespaces:
+ * - Server namespace has knowledge of all locks and is therefore authoritative
+ *   to make decisions like what locks could be granted and what conflicts
+ *   exist during new lock enqueue.
+ * - Client namespace only has limited knowledge about locks in the namespace,
+ *   only seeing locks held by the client.
+ *
+ * Every Lustre service has one server namespace present on the server serving
+ * that service. Every client connected to the service has a client namespace
+ * for it.
+ * Every lock obtained by client in that namespace is actually represented by
+ * two in-memory locks. One on the server and one on the client. The locks are
+ * linked by a special cookie by which one node can tell to the other which lock
+ * it actually means during communications. Such locks are called remote locks.
+ * The locks held by server only without any reference to a client are called
+ * local locks.
+ */
 struct ldlm_namespace {
         /**
          * Namespace name. Used for logging, etc.
@@ -411,69 +484,122 @@ struct ldlm_namespace {
         __u64                  ns_orig_connect_flags;
 
         /**
-         * Hash table for namespace.
+         * Resource hash table for namespace.
+         * Hash table is organized as an array of \see RES_HASH_SIZE elements.
+         * Each element is a list_head linking all resources whose name hash is
+         * equal to the array position.
+         * \see ldlm_hash_fn for the actual hash function.
          */
         cfs_list_t            *ns_hash;
+        /**
+         * Lock protecting accesses to the namespace hashtable
+         */
         cfs_spinlock_t         ns_hash_lock;
 
          /**
-          * Count of resources in the hash.
+          * Number of resources in the hash.
           */
         __u32                  ns_refcount;
 
          /**
-          * All root resources in namespace.
+          * List of all root resources in namespace.
           */
         cfs_list_t             ns_root_list;
 
         /**
-         * Position in global namespace list.
+         * Position in global namespace list linking all namespaces on the node.
          */
         cfs_list_t             ns_list_chain;
 
         /**
-         * All root resources in namespace.
+         * List of unused locks for this namespace. This list is also called
+         * LRU lock list.
+         * Unused locks are locks with zero r/w refcounts. This list is only
+         * used on clients for lock caching purposes.
+         * When we want to release some locks voluntarily or if server want
+         * us to release some locks due to e.g. memory pressure, we take locks
+         * to release from the head of this list.
+         * Locks are linked via l_lru field in \see struct ldlm_lock.
          */
         cfs_list_t             ns_unused_list;
+        /** Number locks in the LRU list above */
         int                    ns_nr_unused;
+        /** All accesses to LRU list must be made under this lock */
         cfs_spinlock_t         ns_unused_lock;
 
+        /**
+         * Maximum number of locks permitted in the LRU. If 0, means locks
+         * are managed by pools and ther is no preset limit, rather it is all
+         * cpontrolled by available memory on this client and on server
+         */
         unsigned int           ns_max_unused;
+        /** Maximum allowed age (last used time) for locks in the LRU */
         unsigned int           ns_max_age;
+        /**
+         * Server only: number of times we evicted clients due to lack of reply
+         * to ASTs
+         */
         unsigned int           ns_timeouts;
-         /**
-          * Seconds.
-          */
+        /**
+         * Seconds.
+         * Appears to be currently unused. Should be removed.
+         */
         unsigned int           ns_ctime_age_limit;
 
         /**
          * Next debug dump, jiffies.
+         * Used to rate-limit ldlm_namespace_dump calls.
+         * \see ldlm_namespace_dump. Increased by 10 seconds every time
+         * its called.
          */
         cfs_time_t             ns_next_dump;
 
+        /** Number of locks in this namespace */
         cfs_atomic_t           ns_locks;
+        /** Number of resources in this namespace */
         __u64                  ns_resources;
+
+        /** "policy" function that does actual lock conflict determination */
         ldlm_res_policy        ns_policy;
+
+        /**
+         * LVB operations for this namespace.
+         * \see struct ldlm_valblock_ops
+         */
         struct ldlm_valblock_ops *ns_lvbo;
+        /**
+         * Used by filter code to store pointer to obd of the service
+         * Should be dropped in favor of \a ns_obd
+         */
         void                  *ns_lvbp;
+        /**
+         * Wait queue used by __ldlm_namespace_free. Get woken up every time
+         * a resource is removed.
+         */
         cfs_waitq_t            ns_waitq;
+        /** ldlm pool structure for this namespace */
         struct ldlm_pool       ns_pool;
+        /** Definition of how eagerly we need to release unused locks from LRU*/
         ldlm_appetite_t        ns_appetite;
 
         /**
          * If more than \a ns_contended_locks found, the resource is considered
          * to be contended.
+         * Lock enqueues might specify that no contended locks should be granted
          */
         unsigned               ns_contended_locks;
 
         /**
-         * The resource remembers contended state during \a ns_contention_time,
-         * in seconds.
+         * The resources in this namespace remember contended state during
+         * \a ns_contention_time, in seconds.
          */
         unsigned               ns_contention_time;
 
         /**
-         * Limit size of nolock requests, in bytes.
+         * Limit size of contended extent locks, in bytes.
+         * If extended lock is requested for more then this much bytes and
+         * caller instructs us not to grant contended locks, we would disregard
+         * such a request.
          */
         unsigned               ns_max_nolock_size;
 
@@ -482,9 +608,18 @@ struct ldlm_namespace {
          */
         struct obd_device     *ns_obd;
 
-        struct adaptive_timeout ns_at_estimate;/* estimated lock callback time*/
+        /**
+         * estimated lock callback time.
+         * Used by AT code to avoid spurious client evictions due to
+         * unresponsiveness where in fact it is network or overall system load
+         * is at fault
+         */
+        struct adaptive_timeout ns_at_estimate;
 };
 
+/**
+ * Returns 1 if namespace \param ns is a client namespace
+ */
 static inline int ns_is_client(struct ldlm_namespace *ns)
 {
         LASSERT(ns != NULL);
@@ -495,6 +630,9 @@ static inline int ns_is_client(struct ldlm_namespace *ns)
         return ns->ns_client == LDLM_NAMESPACE_CLIENT;
 }
 
+/**
+ * Returns 1 if namespace \param ns is a server namespace
+ */
 static inline int ns_is_server(struct ldlm_namespace *ns)
 {
         LASSERT(ns != NULL);
@@ -505,6 +643,9 @@ static inline int ns_is_server(struct ldlm_namespace *ns)
         return ns->ns_client == LDLM_NAMESPACE_SERVER;
 }
 
+/**
+ * Returns 1 if this namespace supports lru_resize
+ */
 static inline int ns_connect_lru_resize(struct ldlm_namespace *ns)
 {
         LASSERT(ns != NULL);
@@ -512,26 +653,29 @@ static inline int ns_connect_lru_resize(struct ldlm_namespace *ns)
 }
 
 /*
- *
- * Resource hash table
+ * Resource hash table definitions.
+ * \see struct ldlm_namespace ns_hash member
  *
  */
-
 #define RES_HASH_BITS 12
 #define RES_HASH_SIZE (1UL << RES_HASH_BITS)
 #define RES_HASH_MASK (RES_HASH_SIZE - 1)
 
 struct ldlm_lock;
 
+/** Type for blocking callback function of a lock. */
 typedef int (*ldlm_blocking_callback)(struct ldlm_lock *lock,
                                       struct ldlm_lock_desc *new, void *data,
                                       int flag);
+/** Type for completion callback function of a lock */
 typedef int (*ldlm_completion_callback)(struct ldlm_lock *lock, int flags,
                                         void *data);
+/** Type for glimpse callback function of a lock */
 typedef int (*ldlm_glimpse_callback)(struct ldlm_lock *lock, void *data);
+/** Type for weight callback function of a lock */
 typedef unsigned long (*ldlm_weigh_callback)(struct ldlm_lock *lock);
 
-/* Interval node data for each LDLM_EXTENT lock */
+/** Interval node data for each LDLM_EXTENT lock */
 struct ldlm_interval {
         struct interval_node li_node;   /* node for tree mgmt */
         cfs_list_t           li_group;  /* the locks which have the same
@@ -539,18 +683,25 @@ struct ldlm_interval {
 };
 #define to_ldlm_interval(n) container_of(n, struct ldlm_interval, li_node)
 
-/* the interval tree must be accessed inside the resource lock. */
+/**
+ * Interval tree for extent locks.
+ * the interval tree must be accessed under the resource lock.
+ * Interval trees are used for granted extent locks to speed up conflicts
+ * lookup. See ldlm/interval_tree.c for more details.
+ */
 struct ldlm_interval_tree {
-        /* tree size, this variable is used to count
-         * granted PW locks in ldlm_extent_policy()*/
+        /** Tree size. */
         int                   lit_size;
         ldlm_mode_t           lit_mode; /* lock mode */
-        struct interval_node *lit_root; /* actually ldlm_interval */
+        struct interval_node *lit_root; /* actual ldlm_interval */
 };
 
+/**
+ * Whenever to track references to exports by ldlm locks
+ */
 #define LUSTRE_TRACKS_LOCK_EXP_REFS (1)
 
-/* Cancel flag. */
+/** Cancel flags. */
 typedef enum {
         LCF_ASYNC      = 0x1, /* Cancel locks asynchronously. */
         LCF_LOCAL      = 0x2, /* Cancel locks locally, not notifing server */
@@ -558,13 +709,23 @@ typedef enum {
                                * in the same RPC */
 } ldlm_cancel_flags_t;
 
+/**
+ * LDLM lock structure
+ *
+ * Represents actual ldlm lock and its state in memory
+ */
 struct ldlm_lock {
         /**
+         * Local lock handle.
+         * When remote side wants to tell us about a lock, they address it by
+         * this handle.
          * Must be first in the structure.
          */
         struct portals_handle    l_handle;
         /**
          * Lock reference count.
+         * This is how many users have pointers to actual structure, so that
+         * we do not accidentally free lock structure that is in use.
          */
         cfs_atomic_t             l_refc;
         /**
@@ -573,15 +734,19 @@ struct ldlm_lock {
          */
         cfs_spinlock_t           l_lock;
         /**
+         * Pointer to actual resource this lock is in.
          * ldlm_lock_change_resource() can change this.
          */
         struct ldlm_resource    *l_resource;
         /**
-         * Protected by ns_hash_lock. List item for client side lru list.
+         * List item for client side lru list.
+         * Protected by ns_hash_lock in struct ldlm_namespace.
          */
         cfs_list_t               l_lru;
         /**
-         * Protected by lr_lock, linkage to resource's lock queues.
+         * Linkage to resource's lock queues according to current lock state.
+         * (could be granted, waiting or converting)
+         * Protected by lr_lock in struct ldlm_resource.
          */
         cfs_list_t               l_res_link;
         /**
@@ -594,7 +759,8 @@ struct ldlm_lock {
          */
         cfs_hlist_node_t         l_exp_hash;
         /**
-         * Protected by lr_lock. Requested mode.
+         * Requested mode.
+         * Protected by lr_lock.
          */
         ldlm_mode_t              l_req_mode;
         /**
@@ -602,42 +768,70 @@ struct ldlm_lock {
          */
         ldlm_mode_t              l_granted_mode;
         /**
-         * Lock enqueue completion handler.
+         * Lock completion handler pointer
+         * Called when the lock is granted.
          */
         ldlm_completion_callback l_completion_ast;
         /**
-         * Lock blocking ast handler.
+         * Lock blocking ast handler pointer.
+         * It plays two roles:
+         * - as a notification of an attempt to queue a conflicting lock (once)
+         * - as a notification when the lock is being cancelled.
+         *
+         * As such the typically it's called twice: once for the initial
+         * conflict and then once more when the last user went away and the lock
+         * is cancelled (could happen recursively).
          */
         ldlm_blocking_callback   l_blocking_ast;
         /**
          * Lock glimpse handler.
+         * Glimpse handler is used to obtain LVB updates from a client by
+         * server
          */
         ldlm_glimpse_callback    l_glimpse_ast;
+
+        /** apparently used "weight" handler. To be removed? */
         ldlm_weigh_callback      l_weigh_ast;
 
         /**
          * Lock export.
+         * This is a pointer to actual client export for locks that were granted
+         * to clients.
+         * Used server-side.
          */
         struct obd_export       *l_export;
         /**
          * Lock connection export.
+         * Pointer to server export on a client.
          */
         struct obd_export       *l_conn_export;
 
         /**
          * Remote lock handle.
+         * If the lock is remote, this is the handle of the other side lock
+         * (l_handle)
          */
         struct lustre_handle     l_remote_handle;
 
+        /**
+         * Representation of private data specific for a lock type.
+         * Examples are: extent range for extent lock or
+         * bitmask for ibits locks */
         ldlm_policy_data_t       l_policy_data;
 
-        /*
-         * Protected by lr_lock. Various counters: readers, writers, etc.
+        /**
+         * Lock state flags.
+         * Like whenever we received any blocking requests for this block, etc.
+         * Protected by lr_lock.
          */
         __u64                 l_flags;
+        /**
+         * Lock r/w usage counters.
+         * Protected by lr_lock.
+         */
         __u32                 l_readers;
         __u32                 l_writers;
-        /*
+        /**
          * Set for locks that were removed from class hash table and will be
          * destroyed when last reference to them is released. Set by
          * ldlm_lock_destroy_internal().
@@ -653,17 +847,19 @@ struct ldlm_lock {
          */
         cfs_waitq_t           l_waitq;
 
-        /** 
+        /**
          * Seconds. it will be updated if there is any activity related to 
          * the lock, e.g. enqueue the lock or send block AST.
          */
         cfs_time_t            l_last_activity;
 
         /**
+         * Time last used by e.g. being matched by lock match.
          * Jiffies. Should be converted to time if needed.
          */
         cfs_time_t            l_last_used;
 
+        /** Originally requested extent for the extent lock */
         struct ldlm_extent    l_req_extent;
 
         /*
@@ -676,52 +872,78 @@ struct ldlm_lock {
         __u32                 l_lvb_len;
         void                 *l_lvb_data;
 
+        /** Private storage for lock user. Opaque to LDLM. */
         void                 *l_ast_data;
-        cfs_spinlock_t        l_extents_list_lock;
-        cfs_list_t            l_extents_list;
-
-        cfs_list_t            l_cache_locks_list;
 
         /*
          * Server-side-only members.
          */
 
-        /** connection cookie for the client originated the operation. */
+        /**
+         * Connection cookie for the client originating the operation.
+         * Used by Commit on Share (COS) code. Currently only used for
+         * inodebits locks on MDS.
+         */
         __u64                 l_client_cookie;
 
         /**
-         * Protected by elt_lock. Callbacks pending.
+         * List item for locks waiting for cancellation from clients.
+         * The lists this could be linked into are:
+         * waiting_locks_list (protected by waiting_locks_spinlock),
+         * then if the lock timed out, it is moved to
+         * expired_lock_thread.elt_expired_locks for further processing.
+         * (Protected by elt_lock)
          */
         cfs_list_t            l_pending_chain;
 
+        /**
+         * Set when lock is sent blocking AST. Time in seconds when timeout
+         * is reached and client holding this lock could be evicted.
+         * This timeout could be further extended by e.g. certain IO activity
+         * under this lock.
+         * \see ost_rw_prolong_locks
+         */
         cfs_time_t            l_callback_timeout;
 
         /**
-         * Pid which created this lock.
+         * Local pid of process which created this lock.
          */
         __u32                 l_pid;
 
         /**
-         * For ldlm_add_ast_work_item().
+         * List item ldlm_add_ast_work_item() for case of blocking ASTs.
          */
         cfs_list_t            l_bl_ast;
         /**
-         * For ldlm_add_ast_work_item().
+         * List item ldlm_add_ast_work_item() for case of completion ASTs.
          */
         cfs_list_t            l_cp_ast;
         /**
-         * For ldlm_add_ast_work_item().
+         * For ldlm_add_ast_work_item() for "revoke" AST used in COS.
          */
         cfs_list_t            l_rk_ast;
 
+        /** Pointer to a conflicting lock that caused blocking AST to be sent
+         * for this lock */
         struct ldlm_lock     *l_blocking_lock;
+        /**
+         * Number of times blocking AST was sent for this lock.
+         * This is for debugging. Valid values are 0 and 1, if there is an
+         * attempt to send blocking ast more than once, an assertion would be
+         * hit. \see ldlm_work_bl_ast_lock
+         */
         int                   l_bl_ast_run;
 
         /**
          * Protected by lr_lock, linkages to "skip lists".
+         * For more explanations of skip lists see ldlm/ldlm_inodebits.c
          */
         cfs_list_t            l_sl_mode;
         cfs_list_t            l_sl_policy;
+
+        /**
+         * Reference tracking structure to debug leaked locks.
+         */
         struct lu_ref         l_reference;
 #if LUSTRE_TRACKS_LOCK_EXP_REFS
         /* Debugging stuff for bug 20498, for tracking export
@@ -735,34 +957,74 @@ struct ldlm_lock {
 #endif
 };
 
+/**
+ * LDLM resource description.
+ * Basically, resource is a representation for a single object.
+ * Object has a name which is currently 4 64 bit integers.
+ * LDLM user is responsible for creation of a mapping between objects it wants
+ * to be protected and resource names.
+ *
+ * A resurce can only hold locks of a single lock type.
+ */
 struct ldlm_resource {
+        /** Back link to namespace */
         struct ldlm_namespace *lr_namespace;
 
-        /* protected by ns_hash_lock */
+        /**
+         * List item for list in namespace hash.
+         * protected by ns_hash_lock
+         */
         cfs_list_t             lr_hash;
+        /* XXX Remove lr_parent/child and its logic ASAP */
         struct ldlm_resource  *lr_parent;   /* 0 for a root resource */
         cfs_list_t             lr_children; /* list head for child resources */
         cfs_list_t             lr_childof;  /* part of ns_root_list if root res,
                                              * part of lr_children if child */
+        /** Spinlock to protect locks under this resource. */
         cfs_spinlock_t         lr_lock;
 
-        /* protected by lr_lock */
+        /**
+         * protected by lr_lock
+         * @{ */
+        /**
+         * List of locks in granted state
+         */
         cfs_list_t             lr_granted;
+        /**
+         *List of locks waiting to change their granted mode (converted)
+         */
         cfs_list_t             lr_converting;
+        /**
+         * List of locks that could not be granted due to conflicts and
+         * that are waiting for conflicts to go away */
         cfs_list_t             lr_waiting;
+        /** @} */
+
+        /* XXX No longer needed? Remove ASAP */
         ldlm_mode_t            lr_most_restr;
+
+        /**
+         * Type of locks this resource can hold
+         * Only one type per resource.
+         */
         ldlm_type_t            lr_type; /* LDLM_{PLAIN,EXTENT,FLOCK} */
+
+        /** Resource name */
         struct ldlm_res_id     lr_name;
+        /** Reference count for this resource */
         cfs_atomic_t           lr_refcount;
 
+        /**
+         * Interval trees (only for extent locks) for all modes of this resource
+        */
         struct ldlm_interval_tree lr_itree[LCK_MODE_NUM];  /* interval trees*/
 
-        /* Server-side-only lock value block elements */
+        /** Server-side-only lock value block elements */
         cfs_semaphore_t        lr_lvb_sem;
         __u32                  lr_lvb_len;
         void                  *lr_lvb_data;
 
-        /* when the resource was considered as contended */
+        /** when the resource was last considered as contended */
         cfs_time_t             lr_contention_time;
         /**
          * List of references to this resource. For debugging.
@@ -770,26 +1032,18 @@ struct ldlm_resource {
         struct lu_ref          lr_reference;
 };
 
-struct ldlm_ast_work {
-        struct ldlm_lock      *w_lock;
-        int                    w_blocking;
-        struct ldlm_lock_desc  w_desc;
-        cfs_list_t             w_list;
-        int                    w_flags;
-        void                  *w_data;
-        int                    w_datalen;
-};
-
-/* ldlm_enqueue parameters common */
+/**
+ * Common ldlm_enqueue parameters
+ */
 struct ldlm_enqueue_info {
-        __u32 ei_type;   /* Type of the lock being enqueued. */
-        __u32 ei_mode;   /* Mode of the lock being enqueued. */
-        void *ei_cb_bl;  /* blocking lock callback */
-        void *ei_cb_cp;  /* lock completion callback */
-        void *ei_cb_gl;  /* lock glimpse callback */
-        void *ei_cb_wg;  /* lock weigh callback */
-        void *ei_cbdata; /* Data to be passed into callbacks. */
-        short ei_async:1; /* async request */
+        __u32 ei_type;   /** Type of the lock being enqueued. */
+        __u32 ei_mode;   /** Mode of the lock being enqueued. */
+        void *ei_cb_bl;  /** blocking lock callback */
+        void *ei_cb_cp;  /** lock completion callback */
+        void *ei_cb_gl;  /** lock glimpse callback */
+        void *ei_cb_wg;  /** lock weigh callback */
+        void *ei_cbdata; /** Data to be passed into callbacks. */
+        short ei_async:1; /** async request */
 };
 
 extern struct obd_ops ldlm_obd_ops;
@@ -797,6 +1051,11 @@ extern struct obd_ops ldlm_obd_ops;
 extern char *ldlm_lockname[];
 extern char *ldlm_typename[];
 extern char *ldlm_it2str(int it);
+
+/**
+ * Support function for lock information printing into debug logs.
+ * \see LDLM_DEBUG
+ */
 #ifdef LIBCFS_DEBUG
 #define ldlm_lock_debug(cdls, level, lock, file, func, line, fmt, a...) do { \
         CFS_CHECK_STACK();                                              \
@@ -817,6 +1076,9 @@ void _ldlm_lock_debug(struct ldlm_lock *lock, __u32 mask,
                       ...)
         __attribute__ ((format (printf, 4, 5)));
 
+/**
+ * Rate-limited version of lock printing function
+ */
 #define LDLM_DEBUG_LIMIT(mask, lock, fmt, a...) do {                    \
         static cfs_debug_limit_state_t _ldlm_cdls;                      \
         ldlm_lock_debug(&_ldlm_cdls, mask, lock,                        \
@@ -827,6 +1089,7 @@ void _ldlm_lock_debug(struct ldlm_lock *lock, __u32 mask,
 #define LDLM_ERROR(lock, fmt, a...) LDLM_DEBUG_LIMIT(D_ERROR, lock, fmt, ## a)
 #define LDLM_WARN(lock, fmt, a...)  LDLM_DEBUG_LIMIT(D_WARNING, lock, fmt, ## a)
 
+/** Non-rate-limited lock printing function for debugging purposes */
 #define LDLM_DEBUG(lock, fmt, a...)   do {                              \
         ldlm_lock_debug(NULL, D_DLMTRACE, lock,                         \
                         __FILE__, __FUNCTION__, __LINE__,               \
@@ -839,6 +1102,10 @@ void _ldlm_lock_debug(struct ldlm_lock *lock, __u32 mask,
          ((void)0)
 #endif
 
+/**
+ * Just a fancy CDEBUG call with log level preset to LDLM_DEBUG.
+ * For the cases where we do not have actual lock to print along
+ * with a debugging message that is ldlm-related */
 #define LDLM_DEBUG_NOLOCK(format, a...)                 \
         CDEBUG(D_DLMTRACE, "### " format "\n" , ##a)
 
@@ -846,26 +1113,33 @@ typedef int (*ldlm_processing_policy)(struct ldlm_lock *lock, int *flags,
                                       int first_enq, ldlm_error_t *err,
                                       cfs_list_t *work_list);
 
-/*
- * Iterators.
+/**
+ * Return values for lock iterators.
+ * Also used during deciding of lock
+ * granting and cancelling.
  */
-
 #define LDLM_ITER_CONTINUE 1 /* keep iterating */
 #define LDLM_ITER_STOP     2 /* stop iterating */
 
 typedef int (*ldlm_iterator_t)(struct ldlm_lock *, void *);
 typedef int (*ldlm_res_iterator_t)(struct ldlm_resource *, void *);
 
+/** \defgroup ldlm_iterator Lock iterators
+ *
+ * LDLM provides for a way to iterate through every lock on a resource or
+ * namespace. Every resource on namespace.
+ * @{ */
 int ldlm_resource_foreach(struct ldlm_resource *res, ldlm_iterator_t iter,
                           void *closure);
 int ldlm_namespace_foreach(struct ldlm_namespace *ns, ldlm_iterator_t iter,
                            void *closure);
 int ldlm_namespace_foreach_res(struct ldlm_namespace *ns,
                                ldlm_res_iterator_t iter, void *closure);
-
-int ldlm_replay_locks(struct obd_import *imp);
 int ldlm_resource_iterate(struct ldlm_namespace *, const struct ldlm_res_id *,
                            ldlm_iterator_t iter, void *data);
+/** @} ldlm_iterator */
+
+int ldlm_replay_locks(struct obd_import *imp);
 
 /* ldlm_flock.c */
 int ldlm_flock_completion_ast(struct ldlm_lock *lock, int flags, void *data);
@@ -875,16 +1149,42 @@ __u64 ldlm_extent_shift_kms(struct ldlm_lock *lock, __u64 old_kms);
 
 
 /* ldlm_lockd.c */
+/** \defgroup ldlm_srv_ast Server AST handlers
+ * These are AST handlers used by server code.
+ * Their property is that they are just preparing RPCs to be sent to clients.
+ * @{
+ */
 int ldlm_server_blocking_ast(struct ldlm_lock *, struct ldlm_lock_desc *,
                              void *data, int flag);
 int ldlm_server_completion_ast(struct ldlm_lock *lock, int flags, void *data);
 int ldlm_server_glimpse_ast(struct ldlm_lock *lock, void *data);
+/** @} ldlm_srv_ast */
+
+struct ldlm_callback_suite {
+        ldlm_completion_callback lcs_completion;
+        ldlm_blocking_callback   lcs_blocking;
+        ldlm_glimpse_callback    lcs_glimpse;
+        ldlm_weigh_callback      lcs_weigh;
+};
+
+/** \defgroup ldlm_handlers Server ldlm handlers
+ * These are handler functions that should be called by "frontends" such as
+ * MDT or OST to pass through ldlm requests to LDLM for handling
+ * @{
+ */
 int ldlm_handle_enqueue(struct ptlrpc_request *req, ldlm_completion_callback,
                         ldlm_blocking_callback, ldlm_glimpse_callback);
+int ldlm_handle_enqueue0(struct ldlm_namespace *ns, struct ptlrpc_request *req,
+                         const struct ldlm_request *dlm_req,
+                         const struct ldlm_callback_suite *cbs);
 int ldlm_handle_convert(struct ptlrpc_request *req);
+int ldlm_handle_convert0(struct ptlrpc_request *req,
+                         const struct ldlm_request *dlm_req);
 int ldlm_handle_cancel(struct ptlrpc_request *req);
 int ldlm_request_cancel(struct ptlrpc_request *req,
                         const struct ldlm_request *dlm_req, int first);
+/** @} ldlm_handlers */
+
 int ldlm_del_waiting_lock(struct ldlm_lock *lock);
 int ldlm_refresh_waiting_lock(struct ldlm_lock *lock, int timeout);
 void ldlm_revoke_export_locks(struct obd_export *exp);
@@ -902,6 +1202,9 @@ struct ldlm_lock *__ldlm_handle2lock(const struct lustre_handle *, int flags);
 void ldlm_cancel_callback(struct ldlm_lock *);
 int ldlm_lock_remove_from_lru(struct ldlm_lock *);
 
+/**
+ * Obtain a lock reference by its handle.
+ */
 static inline struct ldlm_lock *ldlm_handle2lock(const struct lustre_handle *h)
 {
         return __ldlm_handle2lock(h, 0);
@@ -921,6 +1224,9 @@ ldlm_handle2lock_long(const struct lustre_handle *h, int flags)
         return lock;
 }
 
+/**
+ * Update LVBO on a resource taking into account data from reqest \param r
+ */
 static inline int ldlm_res_lvbo_update(struct ldlm_resource *res,
                                        struct ptlrpc_request *r, int increase)
 {
@@ -1052,21 +1358,25 @@ int ldlm_lock_change_resource(struct ldlm_namespace *, struct ldlm_lock *,
         lu_ref_del(&(res)->lr_reference, __FUNCTION__, cfs_current());  \
 } while (0)
 
-struct ldlm_callback_suite {
-        ldlm_completion_callback lcs_completion;
-        ldlm_blocking_callback   lcs_blocking;
-        ldlm_glimpse_callback    lcs_glimpse;
-        ldlm_weigh_callback      lcs_weigh;
-};
-
 /* ldlm_request.c */
 int ldlm_expired_completion_wait(void *data);
+/** \defgroup ldlm_local_ast Default AST handlers for local locks
+ * These AST handlers are typically used for server-side local locks and are
+ * also used byclient-side lock handlers to perform minimum level base
+ * processing
+ * @{ */
 int ldlm_blocking_ast_nocheck(struct ldlm_lock *lock);
 int ldlm_blocking_ast(struct ldlm_lock *lock, struct ldlm_lock_desc *desc,
                       void *data, int flag);
 int ldlm_glimpse_ast(struct ldlm_lock *lock, void *reqp);
 int ldlm_completion_ast_async(struct ldlm_lock *lock, int flags, void *data);
 int ldlm_completion_ast(struct ldlm_lock *lock, int flags, void *data);
+/** @} ldlm_local_ast */
+
+/** \defgroup ldlm_cli_api API to operate on locks from actual ldlm users.
+ * These are typically used by client and server (*_local versions)
+ * to obtain and release locks
+ * @{ */
 int ldlm_cli_enqueue(struct obd_export *exp, struct ptlrpc_request **reqp,
                      struct ldlm_enqueue_info *einfo,
                      const struct ldlm_res_id *res_id,
@@ -1081,9 +1391,6 @@ int ldlm_prep_elc_req(struct obd_export *exp,
                       struct ptlrpc_request *req,
                       int version, int opc, int canceloff,
                       cfs_list_t *cancels, int count);
-int ldlm_handle_enqueue0(struct ldlm_namespace *ns, struct ptlrpc_request *req,
-                         const struct ldlm_request *dlm_req,
-                         const struct ldlm_callback_suite *cbs);
 int ldlm_cli_enqueue_fini(struct obd_export *exp, struct ptlrpc_request *req,
                           ldlm_type_t type, __u8 with_policy, ldlm_mode_t mode,
                           int *flags, void *lvb, __u32 lvb_len,
@@ -1098,12 +1405,8 @@ int ldlm_cli_enqueue_local(struct ldlm_namespace *ns,
                            void *data, __u32 lvb_len,
                            const __u64 *client_cookie,
                            struct lustre_handle *lockh);
-int ldlm_server_ast(struct lustre_handle *lockh, struct ldlm_lock_desc *new,
-                    void *data, __u32 data_len);
 int ldlm_cli_convert(struct lustre_handle *, int new_mode, __u32 *flags);
 int ldlm_cli_update_pool(struct ptlrpc_request *req);
-int ldlm_handle_convert0(struct ptlrpc_request *req,
-                         const struct ldlm_request *dlm_req);
 int ldlm_cli_cancel(struct lustre_handle *lockh);
 int ldlm_cli_cancel_unused(struct ldlm_namespace *, const struct ldlm_res_id *,
                            ldlm_cancel_flags_t flags, void *opaque);
@@ -1122,6 +1425,7 @@ int ldlm_cancel_resource_local(struct ldlm_resource *res,
                                ldlm_cancel_flags_t cancel_flags, void *opaque);
 int ldlm_cli_cancel_list(cfs_list_t *head, int count,
                          struct ptlrpc_request *req, ldlm_cancel_flags_t flags);
+/** @} ldlm_cli_api */
 
 /* mds/handler.c */
 /* This has to be here because recursive inclusion sucks. */
@@ -1148,23 +1452,26 @@ enum lock_res_type {
         LRT_NEW
 };
 
+/** Lock resource */
 static inline void lock_res(struct ldlm_resource *res)
 {
         cfs_spin_lock(&res->lr_lock);
 }
 
+/** Lock resource with a way to instruct lockdep code about nestedness-safe */
 static inline void lock_res_nested(struct ldlm_resource *res,
                                    enum lock_res_type mode)
 {
         cfs_spin_lock_nested(&res->lr_lock, mode);
 }
 
-
+/** Unlock resource */
 static inline void unlock_res(struct ldlm_resource *res)
 {
         cfs_spin_unlock(&res->lr_lock);
 }
 
+/** Check if resource is already locked, assert if not */
 static inline void check_res_locked(struct ldlm_resource *res)
 {
         LASSERT_SPIN_LOCKED(&res->lr_lock);
@@ -1174,6 +1481,10 @@ struct ldlm_resource * lock_res_and_lock(struct ldlm_lock *lock);
 void unlock_res_and_lock(struct ldlm_lock *lock);
 
 /* ldlm_pool.c */
+/** \defgroup ldlm_pools
+ * Various ldlm pool related functions. There are not used outside of ldlm
+ * @{
+ */
 void ldlm_pools_recalc(ldlm_side_t client);
 int ldlm_pools_init(void);
 void ldlm_pools_fini(void);
@@ -1194,7 +1505,7 @@ void ldlm_pool_set_clv(struct ldlm_pool *pl, __u64 clv);
 void ldlm_pool_set_limit(struct ldlm_pool *pl, __u32 limit);
 void ldlm_pool_add(struct ldlm_pool *pl, struct ldlm_lock *lock);
 void ldlm_pool_del(struct ldlm_pool *pl, struct ldlm_lock *lock);
-
-/** @} ldlm */
+/** @} */
 
 #endif
+/** @} LDLM */
diff --git a/lustre/ldlm/l_lock.c b/lustre/ldlm/l_lock.c
index 88a56fa..3918ba9 100644
--- a/lustre/ldlm/l_lock.c
+++ b/lustre/ldlm/l_lock.c
@@ -44,7 +44,9 @@
 #include <lustre_dlm.h>
 #include <lustre_lib.h>
 
-/*
+/**
+ * Lock a lock and its resource.
+ *
  * ldlm locking uses resource to serialize access to locks
  * but there is a case when we change resource of lock upon
  * enqueue reply. we rely on that lock->l_resource = new_res
@@ -65,6 +67,9 @@ struct ldlm_resource * lock_res_and_lock(struct ldlm_lock *lock)
         return res;
 }
 
+/**
+ * Unlock a lock and its resource previously locked with lock_res_and_lock
+ */
 void unlock_res_and_lock(struct ldlm_lock *lock)
 {
         struct ldlm_resource *res = lock->l_resource;
diff --git a/lustre/ldlm/ldlm_extent.c b/lustre/ldlm/ldlm_extent.c
index 780296d..b9252bb 100644
--- a/lustre/ldlm/ldlm_extent.c
+++ b/lustre/ldlm/ldlm_extent.c
@@ -39,6 +39,16 @@
  * Author: Phil Schwan <phil@clusterfs.com>
  */
 
+/**
+ * This file contains implementation of EXTENT lock type
+ *
+ * EXTENT lock type has a definition of "Extent" represented by
+ * starting and ending offsets (inclusive).
+ * There are several extent lock modes, some of them could be mutually
+ * incompatible. Extent locks are considered incompatible if their modes
+ * are incompatible and their extents intersect.
+ */
+
 #define DEBUG_SUBSYSTEM S_LDLM
 #ifndef __KERNEL__
 # include <liblustre.h>
@@ -56,7 +66,13 @@
 
 #define LDLM_MAX_GROWN_EXTENT (32 * 1024 * 1024 - 1)
 
-/* fixup the ldlm_extent after expanding */
+/**
+ * Fixup the ldlm_extent after expanding.
+ *
+ * After expansion have been done, we might still want to do certain adjusting
+ * based on overal contendedness of the resource and the like to avoid granting
+ * overly wide locks.
+ */
 static void ldlm_extent_internal_policy_fixup(struct ldlm_lock *req,
                                               struct ldlm_extent *new_ex,
                                               int conflicting)
@@ -100,7 +116,8 @@ static void ldlm_extent_internal_policy_fixup(struct ldlm_lock *req,
                  mask, new_ex->end, req_end);
 }
 
-/* The purpose of this function is to return:
+/**
+ * The purpose of this function is to return:
  * - the maximum extent
  * - containing the requested extent
  * - and not overlapping existing conflicting extents outside the requested one
@@ -340,14 +357,17 @@ static enum interval_iter ldlm_extent_compat_cb(struct interval_node *n,
         RETURN(INTERVAL_ITER_CONT);
 }
 
-/* Determine if the lock is compatible with all locks on the queue.
- * We stop walking the queue if we hit ourselves so we don't take
- * conflicting locks enqueued after us into accound, or we'd wait forever.
+/**
+ * Determine if the lock is compatible with all locks on the queue.
+ * 
+ * If \param work_list is provided, conflicting locks are linked there.
+ * If \param work_list is not provided, we exit this function on first conflict.
  *
- * 0 if the lock is not compatible
- * 1 if the lock is compatible
- * 2 if this group lock is compatible and requires no further checking
- * negative error, such as EWOULDBLOCK for group locks
+ * \retval 0 if the lock is not compatible
+ * \retval 1 if the lock is compatible
+ * \retval 2 if \param req is a group lock and it is compatible and requires
+ *           no further checking
+ * \retval negative error, such as EWOULDBLOCK for group locks
  */
 static int
 ldlm_extent_compat_queue(cfs_list_t *queue, struct ldlm_lock *req,
@@ -436,6 +456,11 @@ ldlm_extent_compat_queue(cfs_list_t *queue, struct ldlm_lock *req,
                         lock = cfs_list_entry(tmp, struct ldlm_lock,
                                               l_res_link);
 
+                        /**
+                         * We stop walking the queue if we hit ourselves so
+                         * we don't take conflicting locks enqueued after us
+                         * into account, or we'd wait forever.
+                         */
                         if (req == lock)
                                 break;
 
@@ -611,6 +636,12 @@ destroylock:
         RETURN(compat);
 }
 
+/**
+ * Discard all AST work items from list
+ *
+ * If for whatever reason we do not want to send ASTs to conflicting locks
+ * anymore, disassemble the list with this function
+ */
 static void discard_bl_list(cfs_list_t *bl_list)
 {
         cfs_list_t *tmp, *pos;
@@ -632,13 +663,21 @@ static void discard_bl_list(cfs_list_t *bl_list)
         EXIT;
 }
 
-/* If first_enq is 0 (ie, called from ldlm_reprocess_queue):
-  *   - blocking ASTs have already been sent
-  *   - must call this function with the ns lock held
-  *
-  * If first_enq is 1 (ie, called from ldlm_lock_enqueue):
-  *   - blocking ASTs have not been sent
-  *   - must call this function with the ns lock held once */
+/**
+ * Process a granting attempt for extent lock.
+ * Must be called under ns lock held.
+ *
+ * This function tries to see if there are any conflicts for \param lock in
+ * any of the granted or waiting queues. If no conflict met in both,
+ * the lock is granted.
+ *
+ * If \param first_enq is 0 (ie, called from ldlm_reprocess_queue):
+ *   - blocking ASTs have already been sent
+ *
+ * If \param first_enq is 1 (ie, called from ldlm_lock_enqueue):
+ *   - blocking ASTs have not been sent yet, so list of conflicting locks
+ *     would be collected and ASTs sent.
+ */
 int ldlm_process_extent_lock(struct ldlm_lock *lock, int *flags, int first_enq,
                              ldlm_error_t *err, cfs_list_t *work_list)
 {
@@ -716,7 +755,6 @@ int ldlm_process_extent_lock(struct ldlm_lock *lock, int *flags, int first_enq,
  
                 lock_res(res);
                 if (rc == -ERESTART) {
-
                         /* 15715: The lock was granted and destroyed after
                          * resource lock was dropped. Interval node was freed
                          * in ldlm_lock_destroy. Anyway, this always happens
@@ -856,6 +894,9 @@ static inline int lock_mode_to_index(ldlm_mode_t mode)
         return index;
 }
 
+/**
+ * Add newly granted lock into interval tree for the resource
+ */
 void ldlm_extent_add_lock(struct ldlm_resource *res,
                           struct ldlm_lock *lock)
 {
@@ -893,6 +934,9 @@ void ldlm_extent_add_lock(struct ldlm_resource *res,
         ldlm_resource_add_lock(res, &res->lr_granted, lock);
 }
 
+/**
+ * Remove cancelled lock from reource interval tree
+ */
 void ldlm_extent_unlink_lock(struct ldlm_lock *lock)
 {
         struct ldlm_resource *res = lock->l_resource;
diff --git a/lustre/ldlm/ldlm_flock.c b/lustre/ldlm/ldlm_flock.c
index 8e17167..fcf5155 100644
--- a/lustre/ldlm/ldlm_flock.c
+++ b/lustre/ldlm/ldlm_flock.c
@@ -38,6 +38,28 @@
  * Lustre is a trademark of Sun Microsystems, Inc.
  */
 
+/**
+ * This file implements POSIX lock type for lustre.
+ * it's policy properties are start and end of extent and pid.
+ *
+ * These locks are only done through MDS due to POSIX semantics requiring
+ * e.g. that locks could be only partially released and as such split into
+ * two parts and also two adjacent locks from the same process to be merged
+ * into a single wider lock.
+ *
+ * lock modes are mapped like this:
+ * PR and PW for READ and WRITE locks
+ * NL to request a releasing of a portion of the lock
+ *
+ * these flock locks never timeout.
+ *
+ * This code also has limited support for flock locks (whole file locks from
+ * flock() system call, also called bsd locks). Limitaion is only process
+ * that requested a lcok can release it, so if you share a file descriptor
+ * with another process with this lock held and attempt to release such a lock
+ * from that other process, it won't do anything.
+ */
+
 #define DEBUG_SUBSYSTEM S_LDLM
 
 #ifdef __KERNEL__
@@ -122,6 +144,18 @@ ldlm_flock_destroy(struct ldlm_lock *lock, ldlm_mode_t mode, int flags)
         EXIT;
 }
 
+/**
+ * POSIX locks deadlock detection code.
+ *
+ * Given a new lock \param req and an existing lock it conflicts with
+ * \param blocking_lock, we need to iterate through all blocked posix locks
+ * for this export and see if there is a deadlock condition arising.
+ * (i.e. when one client holds a lock on something and want a lock on something
+ * else and at the same time another client has the opposite situation).
+ *
+ * This function has a horrible double O(n^2) list iterations that really
+ * suck a lot of CPU time on a highly-contended resources.
+ */
 static int
 ldlm_flock_deadlock(struct ldlm_lock *req, struct ldlm_lock *blocking_lock)
 {
@@ -153,6 +187,24 @@ restart:
         return 0;
 }
 
+/**
+ * Process a granting attempt for flock lock.
+ * Must be called under ns lock held.
+ *
+ * This function tries to see if there are any conflicts for \param req in
+ * any of the granted or waiting queues. If no conflict met in both,
+ * the lock is granted.
+ *
+ * It is also responsible for splitting a lock if a portion of the lock
+ * is released.
+ *
+ * If \param first_enq is 0 (ie, called from ldlm_reprocess_queue):
+ *   - blocking ASTs have already been sent
+ *
+ * If \param first_enq is 1 (ie, called from ldlm_lock_enqueue):
+ *   - blocking ASTs have not been sent yet, so list of conflicting locks
+ *     would be collected and ASTs sent.
+ */
 int
 ldlm_process_flock_lock(struct ldlm_lock *req, int *flags, int first_enq,
                         ldlm_error_t *err, cfs_list_t *work_list)
@@ -466,9 +518,9 @@ restart:
         }
 
         /* In case we're reprocessing the requested lock we can't destroy
-         * it until after calling ldlm_ast_work_item() above so that lawi()
-         * can bump the reference count on req. Otherwise req could be freed
-         * before the completion AST can be sent.  */
+         * it until after calling ldlm_add_ast_work_item() above so that laawi()
+         * can bump the reference count on \param req. Otherwise \param req
+         * could be freed before the completion AST can be sent.  */
         if (added)
                 ldlm_flock_destroy(req, mode, *flags);
 
@@ -501,7 +553,7 @@ ldlm_flock_interrupted_wait(void *data)
 }
 
 /**
- * Flock completion calback function.
+ * Flock completion callback function.
  *
  * \param lock [in,out]: A lock to be handled
  * \param flags    [in]: flags
diff --git a/lustre/ldlm/ldlm_inodebits.c b/lustre/ldlm/ldlm_inodebits.c
index 406d059..c9296c3 100644
--- a/lustre/ldlm/ldlm_inodebits.c
+++ b/lustre/ldlm/ldlm_inodebits.c
@@ -39,6 +39,16 @@
  * Author: Phil Schwan <phil@clusterfs.com>
  */
 
+/**
+ * This file contains implementation for IBITS lock type
+ *
+ * IBITS lock type contains a bit mask determining various properties of an
+ * object. Meaning to specific bits are specific to the caller and opaque to
+ * LDLM code.
+ * Locks with non-intersecting bitmasks are considered not conflicting.
+ *
+ */
+
 #define DEBUG_SUBSYSTEM S_LDLM
 #ifndef __KERNEL__
 # include <liblustre.h>
@@ -50,7 +60,22 @@
 
 #include "ldlm_internal.h"
 
-/* Determine if the lock is compatible with all locks on the queue. */
+/**
+ * Determine if the lock is compatible with all locks on the queue.
+ *
+ * If \param work_list is provided, conflicting locks are linked there.
+ * If \param work_list is not provided, we exit this function on first conflict.
+ *
+ * \retval 0 if there are conflicting locks in the \param queue
+ * \retval 1 if the lock is compatible to all locks in \param queue
+ *
+ * IBITS locks in granted queue are organized in bunches of same-mode/same-bits
+ * locks called "skip lists". First lock in the bunch contains a pointer to
+ * the end of the bunch.
+ * This allows us to skip entire bunch when iterating the list in search for
+ * conflicting locks if first lock of the bunch is not conflicting with us.
+ *
+ */
 static int
 ldlm_inodebits_compat_queue(cfs_list_t *queue, struct ldlm_lock *req,
                             cfs_list_t *work_list)
@@ -71,6 +96,11 @@ ldlm_inodebits_compat_queue(cfs_list_t *queue, struct ldlm_lock *req,
 
                 lock = cfs_list_entry(tmp, struct ldlm_lock, l_res_link);
 
+                /**
+                 * We stop walking the queue if we hit ourselves so we don't
+                 * take conflicting locks enqueued after us into account,
+                 * or we'd wait forever.
+                 */
                 if (req == lock)
                         RETURN(compat);
 
@@ -97,8 +127,11 @@ ldlm_inodebits_compat_queue(cfs_list_t *queue, struct ldlm_lock *req,
 
                         /* locks with bits overlapped are conflicting locks */
                         if (lock->l_policy_data.l_inodebits.bits & req_bits) {
-                                /* COS lock from the same client is
-                                   not conflicting */
+                                /**
+                                 * COS lock mode has a special compatibility
+                                 * requirements, it is only compatible to locks
+                                 * from the same client.
+                                 */
                                 if (lock->l_req_mode == LCK_COS &&
                                     lock->l_client_cookie == req->l_client_cookie)
                                         goto not_conflicting;
@@ -133,13 +166,22 @@ ldlm_inodebits_compat_queue(cfs_list_t *queue, struct ldlm_lock *req,
         RETURN(compat);
 }
 
-/* If first_enq is 0 (ie, called from ldlm_reprocess_queue):
-  *   - blocking ASTs have already been sent
-  *   - must call this function with the ns lock held
-  *
-  * If first_enq is 1 (ie, called from ldlm_lock_enqueue):
-  *   - blocking ASTs have not been sent
-  *   - must call this function with the ns lock held once */
+/**
+ * Process a granting attempt for ibits lock.
+ * Must be called under ns lock held
+ *
+ * This function tries to see if there are any conflicts for \param lock in
+ * any of the granted or waiting queues. If no conflict met in both,
+ * the lock is granted.
+ *
+ * If \param first_enq is 0 (ie, called from ldlm_reprocess_queue):
+ *   - blocking ASTs have already been sent
+ *
+ * If \param first_enq is 1 (ie, called from ldlm_lock_enqueue):
+ *   - blocking ASTs have not been sent yet, so list of conflicting locks
+ *     would be collected and ASTs sent.
+ *
+ */
 int ldlm_process_inodebits_lock(struct ldlm_lock *lock, int *flags,
                                 int first_enq, ldlm_error_t *err,
                                 cfs_list_t *work_list)
diff --git a/lustre/ldlm/ldlm_lib.c b/lustre/ldlm/ldlm_lib.c
index 943f0b1..e74270c 100644
--- a/lustre/ldlm/ldlm_lib.c
+++ b/lustre/ldlm/ldlm_lib.c
@@ -34,6 +34,12 @@
  * Lustre is a trademark of Sun Microsystems, Inc.
  */
 
+/**
+ * This file is actually much more related to ptlrpc code than ldlm.
+ * It primarily deals with various client/target related logic
+ * including recovery topics.
+ */
+
 #ifndef EXPORT_SYMTAB
 # define EXPORT_SYMTAB
 #endif
diff --git a/lustre/ldlm/ldlm_lock.c b/lustre/ldlm/ldlm_lock.c
index 834697e..c63d0cd 100644
--- a/lustre/ldlm/ldlm_lock.c
+++ b/lustre/ldlm/ldlm_lock.c
@@ -124,7 +124,9 @@ void ldlm_register_intent(struct ldlm_namespace *ns, ldlm_res_policy arg)
  */
 
 
-/*
+/**
+ * Get a reference on a lock.
+ *
  * Lock refcounts, during creation:
  *   - one special one for allocation, dec'd only once in destroy
  *   - one for being a lock that's in-use
@@ -142,6 +144,11 @@ static void ldlm_lock_free(struct ldlm_lock *lock, size_t size)
         OBD_SLAB_FREE(lock, ldlm_lock_slab, sizeof(*lock));
 }
 
+/**
+ * Release lock reference.
+ *
+ * Also frees the lock if it was last reference.
+ */
 void ldlm_lock_put(struct ldlm_lock *lock)
 {
         ENTRY;
@@ -180,6 +187,9 @@ void ldlm_lock_put(struct ldlm_lock *lock)
         EXIT;
 }
 
+/**
+ * Removes ldlm lock \param lock from lru. Assumes lru is already locked.
+ */
 int ldlm_lock_remove_from_lru_nolock(struct ldlm_lock *lock)
 {
         int rc = 0;
@@ -194,6 +204,9 @@ int ldlm_lock_remove_from_lru_nolock(struct ldlm_lock *lock)
         return rc;
 }
 
+/**
+ * Removes ldlm lock \param lock from lru. Obtains the lru lock first.
+ */
 int ldlm_lock_remove_from_lru(struct ldlm_lock *lock)
 {
         struct ldlm_namespace *ns = lock->l_resource->lr_namespace;
@@ -206,6 +219,9 @@ int ldlm_lock_remove_from_lru(struct ldlm_lock *lock)
         return rc;
 }
 
+/**
+ * Adds ldlm lock \param lock to namespace LRU. Assumes LRU is already locked.
+ */
 void ldlm_lock_add_to_lru_nolock(struct ldlm_lock *lock)
 {
         struct ldlm_namespace *ns = lock->l_resource->lr_namespace;
@@ -217,6 +233,10 @@ void ldlm_lock_add_to_lru_nolock(struct ldlm_lock *lock)
         ns->ns_nr_unused++;
 }
 
+/**
+ * Adds ldlm lock \param lock to namespace LRU. Obtains necessary LRU locks
+ * first.
+ */
 void ldlm_lock_add_to_lru(struct ldlm_lock *lock)
 {
         struct ldlm_namespace *ns = lock->l_resource->lr_namespace;
@@ -227,6 +247,10 @@ void ldlm_lock_add_to_lru(struct ldlm_lock *lock)
         EXIT;
 }
 
+/**
+ * Moves ldlm lock \param lock that is already in namespace LRU to the tail of
+ * the LRU. Performs necessary LRU locking
+ */
 void ldlm_lock_touch_in_lru(struct ldlm_lock *lock)
 {
         struct ldlm_namespace *ns = lock->l_resource->lr_namespace;
@@ -240,11 +264,25 @@ void ldlm_lock_touch_in_lru(struct ldlm_lock *lock)
         EXIT;
 }
 
-/* This used to have a 'strict' flag, which recovery would use to mark an
+/**
+ * Destroy a locked lock helper.
+ *
+ * Used by ldlm_lock_destroy and ldlm_lock_destroy_nolock
+ * Must be called under lock and resource lock.
+ *
+ * Does not actually frees the lock data, rather marks the lock as
+ * destroyed by setting l_destroyed field in the lock to 1.
+ * Destroys a handle->lock association too so that the lock can no longer
+ * be found and removes the lock from lru list.
+ * Actual lock freeing would occur when last lock reference goes away.
+ *
+ * Original comment (of some historical value):
+ * This used to have a 'strict' flag, which recovery would use to mark an
  * in-use lock as needing-to-die.  Lest I am ever tempted to put it back, I
  * shall explain why it's gone: with the new hash table scheme, once you call
  * ldlm_lock_destroy, you can never drop your final references on this lock.
- * Because it's not in the hash table anymore.  -phil */
+ * Because it's not in the hash table anymore.  -phil
+ */
 int ldlm_lock_destroy_internal(struct ldlm_lock *lock)
 {
         ENTRY;
@@ -290,6 +328,9 @@ int ldlm_lock_destroy_internal(struct ldlm_lock *lock)
         return 1;
 }
 
+/**
+ * Destroys a ldlm lock \param lock. Performs necessary locking first.
+ */
 void ldlm_lock_destroy(struct ldlm_lock *lock)
 {
         int first;
@@ -306,6 +347,9 @@ void ldlm_lock_destroy(struct ldlm_lock *lock)
         EXIT;
 }
 
+/**
+ * Destroys a ldlm lock \param lock that is already locked.
+ */
 void ldlm_lock_destroy_nolock(struct ldlm_lock *lock)
 {
         int first;
@@ -325,7 +369,10 @@ static void lock_handle_addref(void *lock)
         LDLM_LOCK_GET((struct ldlm_lock *)lock);
 }
 
-/*
+/**
+ *
+ * Allocate and initialize new lock structure.
+ *
  * usage: pass in a resource on which you have done ldlm_resource_get
  *        pass in a parent lock on which you have done a ldlm_lock_get
  *        after return, ldlm_*_put the resource and parent
@@ -364,9 +411,6 @@ static struct ldlm_lock *ldlm_lock_new(struct ldlm_resource *resource)
         CFS_INIT_LIST_HEAD(&lock->l_handle.h_link);
         class_handle_hash(&lock->l_handle, lock_handle_addref);
 
-        CFS_INIT_LIST_HEAD(&lock->l_extents_list);
-        cfs_spin_lock_init(&lock->l_extents_list_lock);
-        CFS_INIT_LIST_HEAD(&lock->l_cache_locks_list);
         lu_ref_init(&lock->l_reference);
         lu_ref_add(&lock->l_reference, "hash", lock);
         lock->l_callback_timeout = 0;
@@ -380,6 +424,11 @@ static struct ldlm_lock *ldlm_lock_new(struct ldlm_resource *resource)
         RETURN(lock);
 }
 
+/**
+ * Moves ldlm lock \param lock to another resource.
+ * This is used on client when server returns some other lock than requested
+ * (typically as a result of intent operation)
+ */
 int ldlm_lock_change_resource(struct ldlm_namespace *ns, struct ldlm_lock *lock,
                               const struct ldlm_res_id *new_resid)
 {
@@ -438,19 +487,26 @@ int ldlm_lock_change_resource(struct ldlm_namespace *ns, struct ldlm_lock *lock,
         RETURN(0);
 }
 
-/*
- *  HANDLES
+/** \defgroup ldlm_handles LDLM HANDLES
+ * Ways to get hold of locks without any addresses.
+ * @{
  */
 
+/**
+ * Fills in handle for ldlm lock \param lock into supplied \param lockh
+ * Does not take any references.
+ */
 void ldlm_lock2handle(const struct ldlm_lock *lock, struct lustre_handle *lockh)
 {
         lockh->cookie = lock->l_handle.h_cookie;
 }
 
-/* if flags: atomically get the lock and set the flags.
- *           Return NULL if flag already set
+/**
+ * Obtain a lock reference by handle.
+ *
+ * if \param flags: atomically get the lock and set the flags.
+ *              Return NULL if flag already set
  */
-
 struct ldlm_lock *__ldlm_handle2lock(const struct lustre_handle *handle,
                                      int flags)
 {
@@ -494,8 +550,13 @@ struct ldlm_lock *__ldlm_handle2lock(const struct lustre_handle *handle,
         EXIT;
  out:
         return retval;
-}
+} 
+/** @} ldlm_handles */
 
+/**
+ * Fill in "on the wire" representation for given ldlm lock into supplied
+ * lock descriptor \param desc structure.
+ */
 void ldlm_lock2desc(struct ldlm_lock *lock, struct ldlm_lock_desc *desc)
 {
         struct obd_export *exp = lock->l_export?:lock->l_conn_export;
@@ -542,6 +603,11 @@ void ldlm_lock2desc(struct ldlm_lock *lock, struct ldlm_lock_desc *desc)
         }
 }
 
+/**
+ * Add a lock to list of conflicting locks to send AST to.
+ *
+ * Only add if we have not sent a blocking ast to the lock yet.
+ */
 void ldlm_add_bl_work_item(struct ldlm_lock *lock, struct ldlm_lock *new,
                            cfs_list_t *work_list)
 {
@@ -560,6 +626,9 @@ void ldlm_add_bl_work_item(struct ldlm_lock *lock, struct ldlm_lock *new,
         }
 }
 
+/**
+ * Add a lock to list of just granted locks to send completion AST to.
+ */
 void ldlm_add_cp_work_item(struct ldlm_lock *lock, cfs_list_t *work_list)
 {
         if ((lock->l_flags & LDLM_FL_CP_REQD) == 0) {
@@ -571,7 +640,11 @@ void ldlm_add_cp_work_item(struct ldlm_lock *lock, cfs_list_t *work_list)
         }
 }
 
-/* must be called with lr_lock held */
+/**
+ * Aggregator function to add ast work items into a list. Determines
+ * what sort of an ast work needs to be done and calls the proper
+ * adding function.
+ * must be called with lr_lock held */
 void ldlm_add_ast_work_item(struct ldlm_lock *lock, struct ldlm_lock *new,
                             cfs_list_t *work_list)
 {
@@ -584,6 +657,11 @@ void ldlm_add_ast_work_item(struct ldlm_lock *lock, struct ldlm_lock *new,
         EXIT;
 }
 
+/**
+ * Add specified r/w reference to ldlm lock with handle \param lockh.
+ * r/w reference type is determined by \param mode
+ * Calls ldlm_lock_addref_internal
+ */
 void ldlm_lock_addref(struct lustre_handle *lockh, __u32 mode)
 {
         struct ldlm_lock *lock;
@@ -594,6 +672,13 @@ void ldlm_lock_addref(struct lustre_handle *lockh, __u32 mode)
         LDLM_LOCK_PUT(lock);
 }
 
+/**
+ * Helper function.
+ * Add specified r/w reference to ldlm lock \param lock.
+ * r/w reference type is determined by \param mode
+ * Removes lock from LRU if it is there.
+ * Assumes the ldlm lock is already locked.
+ */
 void ldlm_lock_addref_internal_nolock(struct ldlm_lock *lock, __u32 mode)
 {
         ldlm_lock_remove_from_lru(lock);
@@ -611,8 +696,8 @@ void ldlm_lock_addref_internal_nolock(struct ldlm_lock *lock, __u32 mode)
 }
 
 /**
- * Attempts to addref a lock, and fails if lock is already LDLM_FL_CBPENDING
- * or destroyed.
+ * Attempts to add r/w reference to a lock with handle \param lockh, and fails
+ * if lock is already LDLM_FL_CBPENDING or destroyed.
  *
  * \retval 0 success, lock was addref-ed
  *
@@ -638,7 +723,11 @@ int ldlm_lock_addref_try(struct lustre_handle *lockh, __u32 mode)
         return result;
 }
 
-/* only called for local locks */
+/**
+ * Add specified r/w reference to ldlm lock \param lock.
+ * Locks ldlm lock and Calls ldlm_lock_addref_internal to do the work.
+ * only called for local locks
+ */
 void ldlm_lock_addref_internal(struct ldlm_lock *lock, __u32 mode)
 {
         lock_res_and_lock(lock);
@@ -646,10 +735,13 @@ void ldlm_lock_addref_internal(struct ldlm_lock *lock, __u32 mode)
         unlock_res_and_lock(lock);
 }
 
-/* only called in ldlm_flock_destroy and for local locks.
- *  * for LDLM_FLOCK type locks, l_blocking_ast is null, and
- *   * ldlm_lock_remove_from_lru() does nothing, it is safe
- *    * for ldlm_flock_destroy usage by dropping some code */
+/**
+ * Removes r/w reference for ldlm lock \param lock.
+ * Assumes ldlm lock is already locked.
+ * only called in ldlm_flock_destroy and for local locks.
+ * Does NOT add lock to LRU if no r/w references left to accomodate flock locks
+ * that cannot be placed in LRU.
+ */
 void ldlm_lock_decref_internal_nolock(struct ldlm_lock *lock, __u32 mode)
 {
         LDLM_DEBUG(lock, "ldlm_lock_decref(%s)", ldlm_lockname[mode]);
@@ -668,6 +760,14 @@ void ldlm_lock_decref_internal_nolock(struct ldlm_lock *lock, __u32 mode)
         LDLM_LOCK_RELEASE(lock);    /* matches the LDLM_LOCK_GET() in addref */
 }
 
+/**
+ * Removes r/w reference for ldlm lock \param lock.
+ * Locks ldlm lock first.
+ * If the lock is determined to be client lock on a client and r/w refcount
+ * drops to zero and the lock is not blocked, the lock is added to LRU lock
+ * on the namespace.
+ * For blocked ldlm locks if r/w count drops to zero, blocking_ast is called.
+ */
 void ldlm_lock_decref_internal(struct ldlm_lock *lock, __u32 mode)
 {
         struct ldlm_namespace *ns;
@@ -731,6 +831,9 @@ void ldlm_lock_decref_internal(struct ldlm_lock *lock, __u32 mode)
         EXIT;
 }
 
+/**
+ * Decrease r/w refcount for ldlm lock with handle \param lockh
+ */
 void ldlm_lock_decref(struct lustre_handle *lockh, __u32 mode)
 {
         struct ldlm_lock *lock = __ldlm_handle2lock(lockh, 0);
@@ -739,8 +842,13 @@ void ldlm_lock_decref(struct lustre_handle *lockh, __u32 mode)
         LDLM_LOCK_PUT(lock);
 }
 
-/* This will drop a lock reference and mark it for destruction, but will not
- * necessarily cancel the lock before returning. */
+/**
+ * Decrease r/w refcount for ldlm lock with handle \param lockh and mark it for
+ * subsequent cancellation once r/w crefcount drops to zero instead of putting
+ * into LRU.
+ *
+ * Typical usage is for GROUP locks which we cannot allow to be cached.
+ */
 void ldlm_lock_decref_and_cancel(struct lustre_handle *lockh, __u32 mode)
 {
         struct ldlm_lock *lock = __ldlm_handle2lock(lockh, 0);
@@ -762,11 +870,11 @@ struct sl_insert_point {
         cfs_list_t *policy_link;
 };
 
-/*
- * search_granted_lock
+/**
+ * Finds a position to insert the new lock into granted lock list.
+ *
+ * Used for locks eligible for skiplist optimization.
  *
- * Description:
- *      Finds a position to insert the new lock.
  * Parameters:
  *      queue [input]:  the granted list where search acts on;
  *      req [input]:    the lock whose position to be located;
@@ -857,6 +965,10 @@ static void search_granted_lock(cfs_list_t *queue,
         return;
 }
 
+/**
+ * Add a lock into resource granted list after a position described by
+ * \param prev
+ */
 static void ldlm_granted_list_add_lock(struct ldlm_lock *lock,
                                        struct sl_insert_point *prev)
 {
@@ -885,6 +997,10 @@ static void ldlm_granted_list_add_lock(struct ldlm_lock *lock,
         EXIT;
 }
 
+/**
+ * Add a lock to granted list on a resource maintaining skiplist
+ * correctness
+ */
 static void ldlm_grant_lock_with_skiplist(struct ldlm_lock *lock)
 {
         struct sl_insert_point prev;
@@ -897,7 +1013,11 @@ static void ldlm_grant_lock_with_skiplist(struct ldlm_lock *lock)
         EXIT;
 }
 
-/* NOTE: called by
+/**
+ * Perform lock granting bookkeeping.
+ *
+ * Includes putting the lock into granted list and updating lock mode.
+ * NOTE: called by
  *  - ldlm_lock_enqueue
  *  - ldlm_reprocess_queue
  *  - ldlm_lock_convert
@@ -929,7 +1049,10 @@ void ldlm_grant_lock(struct ldlm_lock *lock, cfs_list_t *work_list)
         EXIT;
 }
 
-/* returns a referenced lock or NULL.  See the flag descriptions below, in the
+/**
+ * Search for a lock with given properties in a queue.
+ *
+ * \retval a referenced lock or NULL.  See the flag descriptions below, in the
  * comment above ldlm_lock_match */
 static struct ldlm_lock *search_queue(cfs_list_t *queue,
                                       ldlm_mode_t *mode,
@@ -1005,12 +1128,23 @@ static struct ldlm_lock *search_queue(cfs_list_t *queue,
         return NULL;
 }
 
+/**
+ * Mark lock as "matchable" by OST
+ *
+ * Used to prevent certain races in LOV/OSC where the lock is granted, but LVB
+ * is not yet valid.
+ * Assumes ldlm lock is already locked.
+ */
 void ldlm_lock_allow_match_locked(struct ldlm_lock *lock)
 {
         lock->l_flags |= LDLM_FL_LVB_READY;
         cfs_waitq_signal(&lock->l_waitq);
 }
 
+/**
+ * Mark lock as "matchable" by OST
+ * Locks the lock and then \see ldlm_lock_allow_match_locked
+ */
 void ldlm_lock_allow_match(struct ldlm_lock *lock)
 {
         lock_res_and_lock(lock);
@@ -1018,7 +1152,13 @@ void ldlm_lock_allow_match(struct ldlm_lock *lock)
         unlock_res_and_lock(lock);
 }
 
-/* Can be called in two ways:
+/**
+ * Attempt to find a lock with specified properties.
+ *
+ * Typically returns a reference to matched lock unless LDLM_FL_TEST_LOCK is
+ * set in \param flags
+ *
+ * Can be called in two ways:
  *
  * If 'ns' is NULL, then lockh describes an existing lock that we want to look
  * for a duplicate of.
@@ -1035,7 +1175,7 @@ void ldlm_lock_allow_match(struct ldlm_lock *lock)
  * If 'flags' contains LDLM_FL_TEST_LOCK, then don't actually reference a lock,
  *     just tell us if we would have matched.
  *
- * Returns 1 if it finds an already-existing lock that is compatible; in this
+ * \retval 1 if it finds an already-existing lock that is compatible; in this
  * case, lockh is filled in with a addref()ed lock
  *
  * we also check security context, if that failed we simply return 0 (to keep
@@ -1155,7 +1295,9 @@ ldlm_mode_t ldlm_lock_match(struct ldlm_namespace *ns, int flags,
         return rc ? mode : 0;
 }
 
-/* Returns a referenced lock */
+/**
+ * Create and fill in new ldlm lock with specified properties.
+ * Returns a referenced lock */
 struct ldlm_lock *ldlm_lock_create(struct ldlm_namespace *ns,
                                    const struct ldlm_res_id *res_id,
                                    ldlm_type_t type,
@@ -1211,6 +1353,16 @@ out:
         return NULL;
 }
 
+/**
+ * Enqueue (request) a lock.
+ *
+ * Does not block. As a result of enqueue the lock would be put
+ * into granted or waiting list.
+ *
+ * If namespace has intent policy sent and the lock has LDLM_FL_HAS_INTENT flag
+ * set, skip all the enqueueing and delegate lock processing to intent policy
+ * function.
+ */
 ldlm_error_t ldlm_lock_enqueue(struct ldlm_namespace *ns,
                                struct ldlm_lock **lockp,
                                void *cookie, int *flags)
@@ -1323,7 +1475,12 @@ out:
         return rc;
 }
 
-/* Must be called with namespace taken: queue is waiting or converting. */
+/**
+ * Iterate through all waiting locks on a given resource queue and attempt to
+ * grant them.
+ *
+ * Must be called with resource lock held.
+ */
 int ldlm_reprocess_queue(struct ldlm_resource *res, cfs_list_t *queue,
                          cfs_list_t *work_list)
 {
@@ -1354,10 +1511,11 @@ int ldlm_reprocess_queue(struct ldlm_resource *res, cfs_list_t *queue,
         RETURN(rc);
 }
 
-/* Helper function for ldlm_run_ast_work().
+/**
+ * Helper function for ldlm_run_ast_work().
  *
- * Send an existing rpc set specified by @arg->set and then
- * destroy it. Create new one if @do_create flag is set. */
+ * Send an existing rpc set specified by \param arg->set and then
+ * destroy it. Create new one if \param do_create flag is set. */
 static void
 ldlm_send_and_maybe_create_set(struct ldlm_cb_set_arg *arg, int do_create)
 {
@@ -1374,6 +1532,9 @@ ldlm_send_and_maybe_create_set(struct ldlm_cb_set_arg *arg, int do_create)
         EXIT;
 }
 
+/**
+ * Process a call to blocking ast callback for a lock in ast_work list
+ */
 static int
 ldlm_work_bl_ast_lock(cfs_list_t *tmp, struct ldlm_cb_set_arg *arg)
 {
@@ -1403,6 +1564,9 @@ ldlm_work_bl_ast_lock(cfs_list_t *tmp, struct ldlm_cb_set_arg *arg)
         RETURN(1);
 }
 
+/**
+ * Process a call to completion ast callback for a lock in ast_work list
+ */
 static int
 ldlm_work_cp_ast_lock(cfs_list_t *tmp, struct ldlm_cb_set_arg *arg)
 {
@@ -1441,6 +1605,9 @@ ldlm_work_cp_ast_lock(cfs_list_t *tmp, struct ldlm_cb_set_arg *arg)
         RETURN(rc);
 }
 
+/**
+ * Process a call to revocation ast callback for a lock in ast_work list
+ */
 static int
 ldlm_work_revoke_ast_lock(cfs_list_t *tmp, struct ldlm_cb_set_arg *arg)
 {
@@ -1462,6 +1629,12 @@ ldlm_work_revoke_ast_lock(cfs_list_t *tmp, struct ldlm_cb_set_arg *arg)
         RETURN(1);
 }
 
+/**
+ * Process list of locks in needs of ASTs being sent
+ *
+ * Used on server to send multiple ASTs together instead of sending one by
+ * one.
+ */
 int ldlm_run_ast_work(cfs_list_t *rpc_list, ldlm_desc_ast_t ast_type)
 {
         struct ldlm_cb_set_arg arg;
@@ -1525,6 +1698,10 @@ static int reprocess_one_queue(struct ldlm_resource *res, void *closure)
         return LDLM_ITER_CONTINUE;
 }
 
+/**
+ * Iterate through all resources on a namespace attempting to grant waiting
+ * locks.
+ */
 void ldlm_reprocess_all_ns(struct ldlm_namespace *ns)
 {
         cfs_list_t *tmp;
@@ -1562,6 +1739,14 @@ void ldlm_reprocess_all_ns(struct ldlm_namespace *ns)
         EXIT;
 }
 
+/**
+ * Try to grant all waiting locks on a resource.
+ *
+ * Calls ldlm_reprocess_queue on converting and waiting queues.
+ *
+ * Typicaly is called after some resource locks are cancelled to see
+ * if anything could be granted as a result of that cancellation.
+ */
 void ldlm_reprocess_all(struct ldlm_resource *res)
 {
         CFS_LIST_HEAD(rpc_list);
@@ -1589,6 +1774,10 @@ void ldlm_reprocess_all(struct ldlm_resource *res)
         EXIT;
 }
 
+/**
+ * Helper function to call blocking AST for ldlm lock \param lock in a
+ * "cancelling" mode.
+ */
 void ldlm_cancel_callback(struct ldlm_lock *lock)
 {
         check_res_locked(lock->l_resource);
@@ -1607,6 +1796,9 @@ void ldlm_cancel_callback(struct ldlm_lock *lock)
         lock->l_flags |= LDLM_FL_BL_DONE;
 }
 
+/**
+ * Remove skiplist-enabled ldlm lock \param req from granted list
+ */
 void ldlm_unlink_lock_skiplist(struct ldlm_lock *req)
 {
         if (req->l_resource->lr_type != LDLM_PLAIN &&
@@ -1617,6 +1809,9 @@ void ldlm_unlink_lock_skiplist(struct ldlm_lock *req)
         cfs_list_del_init(&req->l_sl_mode);
 }
 
+/**
+ * Attempts to cancel ldlm lock \param lock that has no r/w references.
+ */
 void ldlm_lock_cancel(struct ldlm_lock *lock)
 {
         struct ldlm_resource *res;
@@ -1657,6 +1852,9 @@ void ldlm_lock_cancel(struct ldlm_lock *lock)
         EXIT;
 }
 
+/**
+ * Set opaq data into the lock that only makes sense to upper layer.
+ */
 int ldlm_lock_set_data(struct lustre_handle *lockh, void *data)
 {
         struct ldlm_lock *lock = ldlm_handle2lock(lockh);
@@ -1670,6 +1868,10 @@ int ldlm_lock_set_data(struct lustre_handle *lockh, void *data)
         RETURN(0);
 }
 
+/**
+ * Iterator function for ldlm_cancel_locks_for_export.
+ * Cancels passed locks.
+ */
 void ldlm_cancel_locks_for_export_cb(void *obj, void *data)
 {
         struct obd_export    *exp = data;
@@ -1687,6 +1889,11 @@ void ldlm_cancel_locks_for_export_cb(void *obj, void *data)
         LDLM_LOCK_RELEASE(lock);
 }
 
+/**
+ * Cancel all locks for given export.
+ *
+ * Typically called on client disconnection/eviction
+ */
 void ldlm_cancel_locks_for_export(struct obd_export *exp)
 {
         cfs_hash_for_each_empty(exp->exp_lock_hash,
@@ -1698,6 +1905,7 @@ void ldlm_cancel_locks_for_export(struct obd_export *exp)
  *
  * A fast variant of ldlm_lock_convert for convertion of exclusive
  * locks. The convertion is always successful.
+ * Used by COS code.
  *
  * \param lock A lock to convert
  * \param new_mode new lock mode
@@ -1727,6 +1935,11 @@ void ldlm_lock_downgrade(struct ldlm_lock *lock, int new_mode)
         EXIT;
 }
 
+/**
+ * Attempt to convert already granted lock to a different mode.
+ *
+ * Currently not implemented
+ */
 struct ldlm_resource *ldlm_lock_convert(struct ldlm_lock *lock, int new_mode,
                                         __u32 *flags)
 {
@@ -1831,6 +2044,11 @@ struct ldlm_resource *ldlm_lock_convert(struct ldlm_lock *lock, int new_mode,
         RETURN(res);
 }
 
+/**
+ * Print lock description into debug log.
+ *
+ * Used when printing all locks on a resource for debug purposes.
+ */
 void ldlm_lock_dump(int level, struct ldlm_lock *lock, int pos)
 {
         struct obd_device *obd = NULL;
@@ -1886,6 +2104,9 @@ void ldlm_lock_dump(int level, struct ldlm_lock *lock, int pos)
                        lock->l_policy_data.l_inodebits.bits);
 }
 
+/**
+ * Print lock with lock handle \param lockh description into a debug log
+ */
 void ldlm_lock_dump_handle(int level, struct lustre_handle *lockh)
 {
         struct ldlm_lock *lock;
@@ -1902,6 +2123,10 @@ void ldlm_lock_dump_handle(int level, struct lustre_handle *lockh)
         LDLM_LOCK_PUT(lock);
 }
 
+/**
+ * Print lock information with custom message into debug log.
+ * Helper function.
+ */
 void _ldlm_lock_debug(struct ldlm_lock *lock, __u32 level,
                       struct libcfs_debug_msg_data *data, const char *fmt,
                       ...)
diff --git a/lustre/ldlm/ldlm_lockd.c b/lustre/ldlm/ldlm_lockd.c
index cf7a5b0..37b9b2c 100644
--- a/lustre/ldlm/ldlm_lockd.c
+++ b/lustre/ldlm/ldlm_lockd.c
@@ -85,8 +85,21 @@ static inline unsigned int ldlm_get_rq_timeout(void)
 }
 
 #ifdef __KERNEL__
-/* w_l_spinlock protects both waiting_locks_list and expired_lock_thread */
-static cfs_spinlock_t waiting_locks_spinlock;   /* BH lock (timer) */
+/**
+ * Protects both waiting_locks_list and expired_lock_thread
+ */
+static cfs_spinlock_t waiting_locks_spinlock;
+
+/**
+ * List for contended locks.
+ *
+ * As soon as a lock is contended, it gets placed on this list and expected
+ * time to get a response is filled in the lock.
+ * Special thread walks the list looking for locks that should be released
+ * and schedules client evictions for those that have not been released in time.
+ *
+ * All access to it should be under waiting_locks_spinlock.
+ */
 static cfs_list_t waiting_locks_list;
 static cfs_timer_t waiting_locks_timer;
 
@@ -149,6 +162,9 @@ static inline int have_expired_locks(void)
         RETURN(need_to_run);
 }
 
+/**
+ * Check expired lock list for expired locks and time out them.
+ */
 static int expired_lock_main(void *arg)
 {
         cfs_list_t *expired = &expired_lock_thread.elt_expired_locks;
@@ -375,7 +391,9 @@ repeat:
         cfs_spin_unlock_bh(&waiting_locks_spinlock);
 }
 
-/*
+/**
+ * Add lock to the list of contended locks.
+ *
  * Indicate that we're waiting for a client to call us back cancelling a given
  * lock.  We add it to the pending-callback chain, and schedule the lock-timeout
  * timer to fire appropriately.  (We round up to the next second, to avoid
@@ -447,7 +465,7 @@ static int ldlm_add_waiting_lock(struct ldlm_lock *lock)
         return ret;
 }
 
-/*
+/**
  * Remove a lock from the pending list, likely because it had its cancellation
  * callback arrive without incident.  This adjusts the lock-timeout timer if
  * needed.  Returns 0 if the lock wasn't pending after all, 1 if it was.
@@ -504,8 +522,8 @@ int ldlm_del_waiting_lock(struct ldlm_lock *lock)
         return ret;
 }
 
-/*
- * Prolong the lock
+/**
+ * Prolong the contended lock waiting time.
  *
  * Called with namespace lock held.
  */
@@ -553,6 +571,10 @@ int ldlm_refresh_waiting_lock(struct ldlm_lock *lock, int timeout)
 }
 #endif /* __KERNEL__ */
 
+/**
+ * Perform lock cleanup if AST sending failed.
+ *
+ */
 static void ldlm_failed_ast(struct ldlm_lock *lock, int rc,
                             const char *ast_type)
 {
@@ -578,6 +600,9 @@ static void ldlm_failed_ast(struct ldlm_lock *lock, int rc,
 #endif
 }
 
+/**
+ * Perform lock cleanup if AST reply came with error.
+ */
 static int ldlm_handle_ast_error(struct ldlm_lock *lock,
                                  struct ptlrpc_request *req, int rc,
                                  const char *ast_type)
@@ -704,7 +729,7 @@ static void ldlm_lock_reorder_req(struct ldlm_lock *lock)
         EXIT;
 }
 
-/*
+/**
  * ->l_blocking_ast() method for server-side locks. This is invoked when newly
  * enqueued server lock conflicts with given one.
  *
@@ -798,6 +823,14 @@ int ldlm_server_blocking_ast(struct ldlm_lock *lock,
         RETURN(rc);
 }
 
+/**
+ * ->l_completion_ast callback for a remote lockin server namespace
+ *
+ *  Sends AST to the client notifying it of lock granting.
+ *  If initial lock response was not sent yet, instead of sending another RPC,
+ *  just mark the lock as granted and client will understand
+ *
+ */
 int ldlm_server_completion_ast(struct ldlm_lock *lock, int flags, void *data)
 {
         struct ldlm_cb_set_arg *arg = data;
@@ -909,6 +942,12 @@ int ldlm_server_completion_ast(struct ldlm_lock *lock, int flags, void *data)
         RETURN(rc);
 }
 
+/**
+ * Server side ->l_glimpse_ast handler for client locks.
+ *
+ * Sends glimpse AST to the client and waits for reply. Then updates
+ * lvbo with the result.
+ */
 int ldlm_server_glimpse_ast(struct ldlm_lock *lock, void *data)
 {
         struct ldlm_resource  *res = lock->l_resource;
@@ -1003,9 +1042,9 @@ static void ldlm_svc_get_eopc(const struct ldlm_request *dlm_req,
         return;
 }
 
-/*
- * Main server-side entry point into LDLM. This is called by ptlrpc service
- * threads to carry out client lock enqueueing requests.
+/**
+ * Main server-side entry point into LDLM for enqueue. This is called by ptlrpc
+ * service threads to carry out client lock enqueueing requests.
  */
 int ldlm_handle_enqueue0(struct ldlm_namespace *ns,
                          struct ptlrpc_request *req,
@@ -1265,6 +1304,9 @@ existing_lock:
         return rc;
 }
 
+/**
+ * Old-style LDLM main entry point for server code enqueue.
+ */
 int ldlm_handle_enqueue(struct ptlrpc_request *req,
                         ldlm_completion_callback completion_callback,
                         ldlm_blocking_callback blocking_callback,
@@ -1288,6 +1330,9 @@ int ldlm_handle_enqueue(struct ptlrpc_request *req,
         return rc;
 }
 
+/**
+ * Main LDLM entry point for server code for lock conversion requests.
+ */
 int ldlm_handle_convert0(struct ptlrpc_request *req,
                          const struct ldlm_request *dlm_req)
 {
@@ -1339,6 +1384,9 @@ int ldlm_handle_convert0(struct ptlrpc_request *req,
         RETURN(0);
 }
 
+/**
+ * Old-style main LDLM entry for server code for lock conversion requests.
+ */
 int ldlm_handle_convert(struct ptlrpc_request *req)
 {
         int rc;
@@ -1354,7 +1402,12 @@ int ldlm_handle_convert(struct ptlrpc_request *req)
         return rc;
 }
 
-/* Cancel all the locks whos handles are packed into ldlm_request */
+/**
+ * Cancel all the locks whose handles are packed into ldlm_request
+ *
+ * Called by server code expecting such combined cancel activity
+ * requests.
+ */
 int ldlm_request_cancel(struct ptlrpc_request *req,
                         const struct ldlm_request *dlm_req, int first)
 {
@@ -1387,6 +1440,10 @@ int ldlm_request_cancel(struct ptlrpc_request *req,
                 res = lock->l_resource;
                 done++;
 
+                /* This code here is an optimisation to only attempt lock
+                 * granting on the resource (that could be cpu-expensive)
+                 * after we are done cancelling lock in that resource.
+                 */
                 if (res != pres) {
                         if (pres != NULL) {
                                 ldlm_reprocess_all(pres);
@@ -1412,6 +1469,11 @@ int ldlm_request_cancel(struct ptlrpc_request *req,
         RETURN(done);
 }
 
+/**
+ * Main LDLM entry point for server code to cancel locks.
+ *
+ * Typically gets called from service handler on LDLM_CANCEL opc.
+ */
 int ldlm_handle_cancel(struct ptlrpc_request *req)
 {
         struct ldlm_request *dlm_req;
@@ -1442,6 +1504,11 @@ int ldlm_handle_cancel(struct ptlrpc_request *req)
         RETURN(0);
 }
 
+/**
+ * Callback handler for receiving incoming blocking ASTs.
+ *
+ * This can only happen on client side.
+ */
 void ldlm_handle_bl_callback(struct ldlm_namespace *ns,
                              struct ldlm_lock_desc *ld, struct ldlm_lock *lock)
 {
@@ -1475,6 +1542,11 @@ void ldlm_handle_bl_callback(struct ldlm_namespace *ns,
         EXIT;
 }
 
+/**
+ * Callback handler for receiving incoming completion ASTs.
+ *
+ * This only can happen on client side.
+ */
 static void ldlm_handle_cp_callback(struct ptlrpc_request *req,
                                     struct ldlm_namespace *ns,
                                     struct ldlm_request *dlm_req,
@@ -1569,6 +1641,13 @@ static void ldlm_handle_cp_callback(struct ptlrpc_request *req,
         EXIT;
 }
 
+/**
+ * Callback handler for receiving incoming glimpse ASTs.
+ *
+ * This only can happen on client side.
+ * After handling the glimpse AST we also consider to drop the lock here if it
+ * is unused locally for a long time.
+ */
 static void ldlm_handle_gl_callback(struct ptlrpc_request *req,
                                     struct ldlm_namespace *ns,
                                     struct ldlm_request *dlm_req,
@@ -1622,6 +1701,16 @@ static int ldlm_callback_reply(struct ptlrpc_request *req, int rc)
 }
 
 #ifdef __KERNEL__
+/**
+ * This function queues a list of locks \param cancels containing \param count
+ * locks for later processing by a blocking thread.
+ * If \param count is zero, then the lock referenced as \param lock is
+ * queued instead.
+ *
+ * The blocking thread would then call ->l_blocking_ast callback in the lock.
+ * If list addition is failed, an error is returned and caller is supposed to
+ * call ->l_blocking_ast itself.
+ */
 static int ldlm_bl_to_thread(struct ldlm_namespace *ns,
                              struct ldlm_lock_desc *ld, struct ldlm_lock *lock,
                              cfs_list_t *cancels, int count)
@@ -1949,6 +2038,11 @@ static int ldlm_callback_handler(struct ptlrpc_request *req)
         RETURN(0);
 }
 
+/**
+ * Main handler for canceld thread.
+ *
+ * Separated into its own thread to avaod deadlocks.
+ */
 static int ldlm_cancel_handler(struct ptlrpc_request *req)
 {
         int rc;
@@ -2118,6 +2212,13 @@ static int ldlm_bl_thread_start(struct ldlm_bl_pool *blp)
         return 0;
 }
 
+/**
+ * Main blocking requests processing thread.
+ *
+ * Callers put locks into its queue by calling ldlm_bl_to_thread.
+ * This thread in the end ends up doing actial call to ->l_blocking_ast
+ * for queued locks.
+ */
 static int ldlm_bl_thread_main(void *arg)
 {
         struct ldlm_bl_pool *blp;
diff --git a/lustre/ldlm/ldlm_plain.c b/lustre/ldlm/ldlm_plain.c
index 5240a32..cd41d46 100644
--- a/lustre/ldlm/ldlm_plain.c
+++ b/lustre/ldlm/ldlm_plain.c
@@ -51,6 +51,15 @@
 
 #include "ldlm_internal.h"
 
+/**
+ * Determine if the lock is compatible with all locks on the queue.
+ *
+ * If \param work_list is provided, conflicting locks are linked there.
+ * If \param work_list is not provided, we exit this function on first conflict.
+ *
+ * \retval 0 if there are conflicting locks in the \param queue
+ * \retval 1 if the lock is compatible to all locks in \param queue
+ */
 static inline int
 ldlm_plain_compat_queue(cfs_list_t *queue, struct ldlm_lock *req,
                         cfs_list_t *work_list)
@@ -66,6 +75,11 @@ ldlm_plain_compat_queue(cfs_list_t *queue, struct ldlm_lock *req,
         cfs_list_for_each(tmp, queue) {
                 lock = cfs_list_entry(tmp, struct ldlm_lock, l_res_link);
 
+                /**
+                 * We stop walking the queue if we hit ourselves so we don't
+                 * take conflicting locks enqueued after us into account,
+                 * or we'd wait forever.
+                 */
                 if (req == lock)
                         RETURN(compat);
 
@@ -101,13 +115,21 @@ ldlm_plain_compat_queue(cfs_list_t *queue, struct ldlm_lock *req,
         RETURN(compat);
 }
 
-/* If first_enq is 0 (ie, called from ldlm_reprocess_queue):
+/**
+ * Process a granting attempt for plain lock.
+ * Must be called under ns lock held.
+ *
+ * This function tries to see if there are any conflicts for \a lock in
+ * any of the granted or waiting queues. If no conflict met in both,
+ * the lock is granted.
+ *
+ * If \a first_enq is 0 (ie, called from ldlm_reprocess_queue):
  *   - blocking ASTs have already been sent
- *   - must call this function with the resource lock held
  *
- * If first_enq is 1 (ie, called from ldlm_lock_enqueue):
- *   - blocking ASTs have not been sent
- *   - must call this function with the resource lock held */
+ * If \a first_enq is 1 (ie, called from ldlm_lock_enqueue):
+ *   - blocking ASTs have not been sent yet, so list of conflicting locks
+ *     would be collected and ASTs sent.
+ */
 int ldlm_process_plain_lock(struct ldlm_lock *lock, int *flags, int first_enq,
                             ldlm_error_t *err, cfs_list_t *work_list)
 {
diff --git a/lustre/ldlm/ldlm_request.c b/lustre/ldlm/ldlm_request.c
index f287f1a..59612b6 100644
--- a/lustre/ldlm/ldlm_request.c
+++ b/lustre/ldlm/ldlm_request.c
@@ -175,7 +175,7 @@ int ldlm_completion_ast_async(struct ldlm_lock *lock, int flags, void *data)
 }
 
 /**
- * Client side LDLM "completion" AST. This is called in several cases:
+ * Generic LDLM "completion" AST. This is called in several cases:
  *
  *     - when a reply to an ENQUEUE rpc is received from the server
  *       (ldlm_cli_enqueue_fini()). Lock might be granted or not granted at
@@ -344,7 +344,7 @@ int ldlm_blocking_ast(struct ldlm_lock *lock, struct ldlm_lock_desc *desc,
         RETURN(ldlm_blocking_ast_nocheck(lock));
 }
 
-/*
+/**
  * ->l_glimpse_ast() for DLM extent locks acquired on the server-side. See
  * comment in filter_intent_policy() on why you may need this.
  */
@@ -371,6 +371,9 @@ int ldlm_glimpse_ast(struct ldlm_lock *lock, void *reqp)
         return -ELDLM_NO_LOCK_DATA;
 }
 
+/**
+ * Enqueue a local lock (typically on a server).
+ */
 int ldlm_cli_enqueue_local(struct ldlm_namespace *ns,
                            const struct ldlm_res_id *res_id,
                            ldlm_type_t type, ldlm_policy_data_t *policy,
@@ -474,6 +477,11 @@ static void failed_lock_cleanup(struct ldlm_namespace *ns,
         }
 }
 
+/**
+ * Finishing portion of client lock enqueue code.
+ *
+ * Called after receiving reply from server.
+ */
 int ldlm_cli_enqueue_fini(struct obd_export *exp, struct ptlrpc_request *req,
                           ldlm_type_t type, __u8 with_policy, ldlm_mode_t mode,
                           int *flags, void *lvb, __u32 lvb_len,
@@ -641,7 +649,9 @@ cleanup:
         return rc;
 }
 
-/* PAGE_SIZE-512 is to allow TCP/IP and LNET headers to fit into
+/**
+ * Estimate number of loc handles that would fit into request of given size.
+ * PAGE_SIZE-512 is to allow TCP/IP and LNET headers to fit into
  * a single page on the send/receive side. XXX: 512 should be changed
  * to more adequate value. */
 static inline int ldlm_req_handles_avail(int req_size, int off)
@@ -674,8 +684,13 @@ static inline int ldlm_format_handles_avail(struct obd_import *imp,
         return ldlm_req_handles_avail(size, off);
 }
 
-/* Cancel lru locks and pack them into the enqueue request. Pack there the given
- * @count locks in @cancels. */
+/**
+ * Cancel lru locks and pack them into the enqueue request. Pack there the given
+ * \param count locks in \param cancels.
+ *
+ * This is to be called by functions preparing their own requests that
+ * might contain lists of locks to cancel in addition to actual operation
+ * that needs to be performed. */
 int ldlm_prep_elc_req(struct obd_export *exp, struct ptlrpc_request *req,
                       int version, int opc, int canceloff,
                       cfs_list_t *cancels, int count)
@@ -747,12 +762,16 @@ int ldlm_prep_enqueue_req(struct obd_export *exp, struct ptlrpc_request *req,
                                  LDLM_ENQUEUE_CANCEL_OFF, cancels, count);
 }
 
-/* If a request has some specific initialisation it is passed in @reqp,
+/**
+ * Client-side lock enqueue.
+ *
+ * If a request has some specific initialisation it is passed in @reqp,
  * otherwise it is created in ldlm_cli_enqueue.
  *
  * Supports sync and async requests, pass @async flag accordingly. If a
  * request was created in ldlm_cli_enqueue and it is the async request,
- * pass it to the caller in @reqp. */
+ * pass it to the caller in @reqp.
+ */
 int ldlm_cli_enqueue(struct obd_export *exp, struct ptlrpc_request **reqp,
                      struct ldlm_enqueue_info *einfo,
                      const struct ldlm_res_id *res_id,
@@ -994,11 +1013,13 @@ int ldlm_cli_convert(struct lustre_handle *lockh, int new_mode, __u32 *flags)
         return rc;
 }
 
-/* Cancel locks locally.
+/**
+ * Cancel locks locally.
  * Returns:
- * LDLM_FL_LOCAL_ONLY if tere is no need in a CANCEL rpc to the server;
- * LDLM_FL_CANCELING otherwise;
- * LDLM_FL_BL_AST if there is a need in a separate CANCEL rpc. */
+ * \retval LDLM_FL_LOCAL_ONLY if there is no need in a CANCEL rpc to the server;
+ * \retval LDLM_FL_CANCELING otherwise;
+ * \retval LDLM_FL_BL_AST if there is a need in a separate CANCEL rpc.
+ */
 static int ldlm_cli_cancel_local(struct ldlm_lock *lock)
 {
         int rc = LDLM_FL_LOCAL_ONLY;
@@ -1037,8 +1058,10 @@ static int ldlm_cli_cancel_local(struct ldlm_lock *lock)
         RETURN(rc);
 }
 
-/* Pack @count locks in @head into ldlm_request buffer at the offset @off,
-   of the request @req. */
+/**
+ * Pack \param count locks in \param head into ldlm_request buffer at
+ * the offset \param off, * of the request \param req.
+ */
 static void ldlm_cancel_pack(struct ptlrpc_request *req,
                              cfs_list_t *head, int count)
 {
@@ -1073,8 +1096,9 @@ static void ldlm_cancel_pack(struct ptlrpc_request *req,
         EXIT;
 }
 
-/* Prepare and send a batched cancel rpc, it will include count lock handles
- * of locks given in @head. */
+/**
+ * Prepare and send a batched cancel rpc, it will include \param count lock
+ * handles of locks given in \param cancels list. */
 int ldlm_cli_cancel_req(struct obd_export *exp, cfs_list_t *cancels,
                         int count, ldlm_cancel_flags_t flags)
 {
@@ -1169,7 +1193,8 @@ static inline struct ldlm_pool *ldlm_imp2pl(struct obd_import *imp)
 }
 
 /**
- * Update client's obd pool related fields with new SLV and Limit from \a req.
+ * Update client's obd pool related fields with new SLV and Limit from
+ * \param req.
  */
 int ldlm_cli_update_pool(struct ptlrpc_request *req)
 {
@@ -1223,6 +1248,11 @@ int ldlm_cli_update_pool(struct ptlrpc_request *req)
 }
 EXPORT_SYMBOL(ldlm_cli_update_pool);
 
+/**
+ * Client side lock cancel.
+ *
+ * Lock must not have any readers or writers by this time.
+ */
 int ldlm_cli_cancel(struct lustre_handle *lockh)
 {
         struct obd_export *exp;
@@ -1312,8 +1342,9 @@ static int ldlm_cancel_list(cfs_list_t *cancels, int count,
 
 /**
  * Callback function for lru-resize policy. Makes decision whether to keep
- * \a lock in LRU for current \a LRU size \a unused, added in current scan
- * \a added and number of locks to be preferably canceled \a count.
+ * \param lock in LRU for current \param LRU size \param unused, added in
+ * current scan \param added and number of locks to be preferably canceled
+ * \param count.
  *
  * \retval LDLM_POLICY_KEEP_LOCK keep lock in LRU in stop scanning
  *
@@ -1357,8 +1388,9 @@ static ldlm_policy_res_t ldlm_cancel_lrur_policy(struct ldlm_namespace *ns,
 
 /**
  * Callback function for proc used policy. Makes decision whether to keep
- * \a lock in LRU for current \a LRU size \a unused, added in current scan
- * \a added and number of locks to be preferably canceled \a count.
+ * \param lock in LRU for current \param LRU size \param unused, added in
+ * current scan \param added and number of locks to be preferably canceled
+ * \param count.
  *
  * \retval LDLM_POLICY_KEEP_LOCK keep lock in LRU in stop scanning
  *
@@ -1379,8 +1411,9 @@ static ldlm_policy_res_t ldlm_cancel_passed_policy(struct ldlm_namespace *ns,
 
 /**
  * Callback function for aged policy. Makes decision whether to keep
- * \a lock in LRU for current \a LRU size \a unused, added in current scan
- * \a added and number of locks to be preferably canceled \a count.
+ * \param lock in LRU for current \param LRU size \param unused, added in
+ * current scan \param added and number of locks to be preferably canceled
+ * \param count.
  *
  * \retval LDLM_POLICY_KEEP_LOCK keep lock in LRU in stop scanning
  *
@@ -1404,8 +1437,9 @@ static ldlm_policy_res_t ldlm_cancel_aged_policy(struct ldlm_namespace *ns,
 
 /**
  * Callback function for default policy. Makes decision whether to keep
- * \a lock in LRU for current \a LRU size \a unused, added in current scan
- * \a added and number of locks to be preferably canceled \a count.
+ * \param lock in LRU for current \param LRU size \param unused, added in
+ * current scan \param added and number of locks to be preferably canceled
+ * \param count.
  *
  * \retval LDLM_POLICY_KEEP_LOCK keep lock in LRU in stop scanning
  *
@@ -1447,11 +1481,12 @@ ldlm_cancel_lru_policy(struct ldlm_namespace *ns, int flags)
         return ldlm_cancel_default_policy;
 }
 
-/* - Free space in lru for @count new locks,
+/**
+ * - Free space in lru for \param count new locks,
  *   redundant unused locks are canceled locally;
  * - also cancel locally unused aged locks;
- * - do not cancel more than @max locks;
- * - GET the found locks and add them into the @cancels list.
+ * - do not cancel more than \param max locks;
+ * - GET the found locks and add them into the \param cancels list.
  *
  * A client lock can be added to the l_bl_ast list only when it is
  * marked LDLM_FL_CANCELING. Otherwise, somebody is already doing CANCEL.
@@ -1463,12 +1498,12 @@ ldlm_cancel_lru_policy(struct ldlm_namespace *ns, int flags)
  * Calling policies for enabled lru resize:
  * ----------------------------------------
  * flags & LDLM_CANCEL_LRUR - use lru resize policy (SLV from server) to
- *                            cancel not more than @count locks;
+ *                            cancel not more than \a count locks;
  *
- * flags & LDLM_CANCEL_PASSED - cancel @count number of old locks (located at
+ * flags & LDLM_CANCEL_PASSED - cancel \a count number of old locks (located at
  *                              the beginning of lru list);
  *
- * flags & LDLM_CANCEL_SHRINK - cancel not more than @count locks according to
+ * flags & LDLM_CANCEL_SHRINK - cancel not more than \a count locks according to
  *                              memory pressre policy function;
  *
  * flags & LDLM_CANCEL_AGED -   cancel alocks according to "aged policy".
@@ -1588,10 +1623,14 @@ int ldlm_cancel_lru_local(struct ldlm_namespace *ns, cfs_list_t *cancels,
         RETURN(ldlm_cancel_list(cancels, added, cancel_flags));
 }
 
-/* when called with LDLM_ASYNC the blocking callback will be handled
+/**
+ * Cancel at least \param nr locks from given namespace lru.
+ *
+ * when called with LDLM_ASYNC the blocking callback will be handled
  * in a thread and this function will return after the thread has been
  * asked to call the callback.  when called with LDLM_SYNC the blocking
- * callback will be performed in this function. */
+ * callback will be performed in this function.
+ */
 int ldlm_cancel_lru(struct ldlm_namespace *ns, int nr, ldlm_sync_t sync,
                     int flags)
 {
@@ -1615,9 +1654,11 @@ int ldlm_cancel_lru(struct ldlm_namespace *ns, int nr, ldlm_sync_t sync,
         RETURN(count);
 }
 
-/* Find and cancel locally unused locks found on resource, matched to the
- * given policy, mode. GET the found locks and add them into the @cancels
- * list. */
+/**
+ * Find and cancel locally unused locks found on resource, matched to the
+ * given policy, mode. GET the found locks and add them into the \param cancels
+ * list.
+ */
 int ldlm_cancel_resource_local(struct ldlm_resource *res,
                                cfs_list_t *cancels,
                                ldlm_policy_data_t *policy,
@@ -1670,12 +1711,16 @@ int ldlm_cancel_resource_local(struct ldlm_resource *res,
         RETURN(ldlm_cancel_list(cancels, count, cancel_flags));
 }
 
-/* If @req is NULL, send CANCEL request to server with handles of locks
- * in the @cancels. If EARLY_CANCEL is not supported, send CANCEL requests
+/**
+ * Cancel client-side locks from a list and send/prepare cancel RPCs to the
+ * server.
+ * If \param req is NULL, send CANCEL request to server with handles of locks
+ * in the \param cancels. If EARLY_CANCEL is not supported, send CANCEL requests
  * separately per lock.
- * If @req is not NULL, put handles of locks in @cancels into the request
- * buffer at the offset @off.
- * Destroy @cancels at the end. */
+ * If \param req is not NULL, put handles of locks in @cancels into the request
+ * buffer at the offset \param off.
+ * Destroy \param cancels at the end.
+ */
 int ldlm_cli_cancel_list(cfs_list_t *cancels, int count,
                          struct ptlrpc_request *req, ldlm_cancel_flags_t flags)
 {
@@ -1722,6 +1767,11 @@ int ldlm_cli_cancel_list(cfs_list_t *cancels, int count,
         RETURN(0);
 }
 
+/**
+ * Cancel all locks on a resource that have 0 readers/writers.
+ *
+ * If flags & LDLM_FL_LOCAL_ONLY, throw the locks away without trying
+ * to notify the server. */
 int ldlm_cli_cancel_unused_resource(struct ldlm_namespace *ns,
                                     const struct ldlm_res_id *res_id,
                                     ldlm_policy_data_t *policy,
@@ -1766,7 +1816,8 @@ static inline int have_no_nsresource(struct ldlm_namespace *ns)
         RETURN(no_resource);
 }
 
-/* Cancel all locks on a namespace (or a specific resource, if given)
+/**
+ * Cancel all locks on a namespace (or a specific resource, if given)
  * that have 0 readers/writers.
  *
  * If flags & LCF_LOCAL, throw the locks away without trying
diff --git a/lustre/ldlm/ldlm_resource.c b/lustre/ldlm/ldlm_resource.c
index 20e9e16..770605e 100644
--- a/lustre/ldlm/ldlm_resource.c
+++ b/lustre/ldlm/ldlm_resource.c
@@ -313,6 +313,9 @@ void ldlm_proc_namespace(struct ldlm_namespace *ns)
 #define ldlm_proc_namespace(ns) do {} while (0)
 #endif /* LPROCFS */
 
+/**
+ * Create and initialize new empty namespace.
+ */
 struct ldlm_namespace *ldlm_namespace_new(struct obd_device *obd, char *name,
                                           ldlm_side_t client, ldlm_appetite_t apt)
 {
@@ -399,7 +402,10 @@ out_ref:
 
 extern struct ldlm_lock *ldlm_lock_get(struct ldlm_lock *lock);
 
-/* If flags contains FL_LOCAL_ONLY, don't try to tell the server, just cleanup.
+/**
+ * Cancel and destroy all locks on a resource.
+ *
+ * If flags contains FL_LOCAL_ONLY, don't try to tell the server, just cleanup.
  * This is currently only used for recovery, and we make certain assumptions
  * as a result--notably, that we shouldn't cancel locks with refs. -phil
  *
@@ -480,6 +486,13 @@ static void cleanup_resource(struct ldlm_resource *res, cfs_list_t *q,
         EXIT;
 }
 
+/**
+ * Cancel and destroy all locks in the namespace.
+ *
+ * Typically used during evictions when server notified client that it was
+ * evicted and all of its state needs to be destroyed.
+ * Also used during shutdown.
+ */
 int ldlm_namespace_cleanup(struct ldlm_namespace *ns, int flags)
 {
         cfs_list_t *tmp;
@@ -535,6 +548,11 @@ int ldlm_namespace_cleanup(struct ldlm_namespace *ns, int flags)
         return ELDLM_OK;
 }
 
+/**
+ * Attempts to free namespace.
+ *
+ * Only used when namespace goes away, like during an unmount.
+ */
 static int __ldlm_namespace_free(struct ldlm_namespace *ns, int force)
 {
         ENTRY;
@@ -580,13 +598,13 @@ force_wait:
 }
 
 /**
- * Performs various cleanups for passed \a ns to make it drop refc and be ready
- * for freeing. Waits for refc == 0.
+ * Performs various cleanups for passed \param ns to make it drop refc and be
+ * ready for freeing. Waits for refc == 0.
  *
  * The following is done:
- * (0) Unregister \a ns from its list to make inaccessible for potential users
- * like pools thread and others;
- * (1) Clear all locks in \a ns.
+ * (0) Unregister \param ns from its list to make inaccessible for potential
+ * users like pools thread and others;
+ * (1) Clear all locks in \param ns.
  */
 void ldlm_namespace_free_prior(struct ldlm_namespace *ns,
                                struct obd_import *imp,
@@ -621,9 +639,9 @@ void ldlm_namespace_free_prior(struct ldlm_namespace *ns,
 }
 
 /**
- * Performs freeing memory structures related to \a ns. This is only done when
- * ldlm_namespce_free_prior() successfully removed all resources referencing
- * \a ns and its refc == 0.
+ * Performs freeing memory structures related to \param ns. This is only done
+ * when * ldlm_namespce_free_prior() successfully removed all resources
+ * referencing \param ns and its refc == 0.
  */
 void ldlm_namespace_free_post(struct ldlm_namespace *ns)
 {
@@ -662,8 +680,9 @@ void ldlm_namespace_free_post(struct ldlm_namespace *ns)
         OBD_FREE(ns->ns_name, strlen(ns->ns_name) + 1);
 
         /*
-         * Namespace \a ns should be not on list in this time, otherwise this
-         * will cause issues realted to using freed \a ns in pools thread.
+         * Namespace \param ns should be not on list in this time, otherwise
+         * this will cause issues realted to using freed \param ns in pools
+         * thread.
          */
         LASSERT(cfs_list_empty(&ns->ns_list_chain));
         OBD_FREE_PTR(ns);
@@ -672,7 +691,8 @@ void ldlm_namespace_free_post(struct ldlm_namespace *ns)
 }
 
 
-/* Cleanup the resource, and free namespace.
+/**
+ * Cleanup the resource, and free namespace.
  * bug 12864:
  * Deadlock issue:
  * proc1: destroy import
@@ -725,7 +745,9 @@ void ldlm_namespace_put(struct ldlm_namespace *ns, int wakeup)
         cfs_spin_unlock(&ns->ns_hash_lock);
 }
 
-/* Register @ns in the list of namespaces */
+/**
+ * Register \param ns in the list of namespaces
+ */
 void ldlm_namespace_register(struct ldlm_namespace *ns, ldlm_side_t client)
 {
         cfs_mutex_down(ldlm_namespace_lock(client));
@@ -735,7 +757,9 @@ void ldlm_namespace_register(struct ldlm_namespace *ns, ldlm_side_t client)
         cfs_mutex_up(ldlm_namespace_lock(client));
 }
 
-/* Unregister @ns from the list of namespaces */
+/**
+ * Unregister \param ns from the list of namespaces
+ */
 void ldlm_namespace_unregister(struct ldlm_namespace *ns, ldlm_side_t client)
 {
         cfs_mutex_down(ldlm_namespace_lock(client));
@@ -766,6 +790,11 @@ struct ldlm_namespace *ldlm_namespace_first_locked(ldlm_side_t client)
         return container_of(ldlm_namespace_list(client)->next,
                 struct ldlm_namespace, ns_list_chain);
 }
+
+/**
+ * Calculate hash value for a given resource name for the purposes of
+ * locating hte resource in namespace resource hash
+ */
 static __u32 ldlm_hash_fn(struct ldlm_resource *parent,
                           const struct ldlm_res_id *name)
 {
@@ -780,6 +809,9 @@ static __u32 ldlm_hash_fn(struct ldlm_resource *parent,
         return (hash & RES_HASH_MASK);
 }
 
+/**
+ * Create and initialize new resource.
+ */
 static struct ldlm_resource *ldlm_resource_new(void)
 {
         struct ldlm_resource *res;
@@ -815,7 +847,11 @@ static struct ldlm_resource *ldlm_resource_new(void)
         return res;
 }
 
-/* must be called with hash lock held */
+/**
+ * Get an existing resource reference by name.
+ *
+ * must be called with hash lock held
+ */
 static struct ldlm_resource *
 ldlm_resource_find(struct ldlm_namespace *ns, const struct ldlm_res_id *name,
                    __u32 hash)
@@ -835,7 +871,7 @@ ldlm_resource_find(struct ldlm_namespace *ns, const struct ldlm_res_id *name,
         return NULL;
 }
 
-/* Args: locked namespace
+/* Args: namespace with ns_lock held.
  * Returns: newly-allocated, referenced, unlocked resource */
 static struct ldlm_resource *
 ldlm_resource_add(struct ldlm_namespace *ns, struct ldlm_resource *parent,
@@ -901,7 +937,9 @@ ldlm_resource_add(struct ldlm_namespace *ns, struct ldlm_resource *parent,
         RETURN(res);
 }
 
-/* Args: unlocked namespace
+/**
+ * Return a reference to resource with given name creating it if necessary.
+ * Args: namespace with ns_lock unlocked
  * Locks: takes and releases ns->ns_lock and res->lr_lock
  * Returns: referenced, unlocked ldlm_resource or NULL */
 struct ldlm_resource *
@@ -1034,6 +1072,9 @@ int ldlm_resource_putref_locked(struct ldlm_resource *res)
         RETURN(rc);
 }
 
+/**
+ * Add a lock into a given resource into specified lock list.
+ */
 void ldlm_resource_add_lock(struct ldlm_resource *res, cfs_list_t *head,
                             struct ldlm_lock *lock)
 {
@@ -1053,6 +1094,11 @@ void ldlm_resource_add_lock(struct ldlm_resource *res, cfs_list_t *head,
         cfs_list_add_tail(&lock->l_res_link, head);
 }
 
+/**
+ * Insert a lock into resource after specified lock
+ *
+ * Obtain resource description from the lock we are inserting after.
+ */
 void ldlm_resource_insert_lock_after(struct ldlm_lock *original,
                                      struct ldlm_lock *new)
 {
@@ -1093,6 +1139,9 @@ void ldlm_res2desc(struct ldlm_resource *res, struct ldlm_resource_desc *desc)
         desc->lr_name = res->lr_name;
 }
 
+/**
+ * Print information about all locks in all namespaces on this node to debug log
+ */
 void ldlm_dump_all_namespaces(ldlm_side_t client, int level)
 {
         cfs_list_t *tmp;
@@ -1111,6 +1160,9 @@ void ldlm_dump_all_namespaces(ldlm_side_t client, int level)
         cfs_mutex_up(ldlm_namespace_lock(client));
 }
 
+/**
+ * Print information about all locks in this namespace on this node to debug log
+ */
 void ldlm_namespace_dump(int level, struct ldlm_namespace *ns)
 {
         cfs_list_t *tmp;
@@ -1148,6 +1200,9 @@ void ldlm_namespace_dump(int level, struct ldlm_namespace *ns)
         cfs_spin_unlock(&ns->ns_hash_lock);
 }
 
+/**
+ * Print information about all locks in this resource to debug log
+ */
 void ldlm_resource_dump(int level, struct ldlm_resource *res)
 {
         cfs_list_t *tmp;
