[LU-1914] Doxygen comments - ldlm module

• Type: Technical task
• Resolution: Fixed
• Priority: Minor
• Fix Version/s: Lustre 2.4.0
• Labels: documentation
• Bugzilla ID: 20,943
• Assignee: Ned Bass (Inactive)
• Reporter: Ned Bass (Inactive)

Description

Update the attached patch from Bug 20943, which adds doxygen comments to the ldlm module, for master.

Comments

[Ned Bass (Inactive)]

patch landed to master

[Ned Bass (Inactive)]

http://review.whamcloud.com/#change,3985

[Ned Bass (Inactive)]

I have a few questions about this patch.

         /**
-         * 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;

The ldlm namespace resource hashtable now appears to use the generic cfs hash implementation, so I think we can omit any hash table implementation details here.

-         /**
-          * Seconds.
-          */
+        /**
+         * Seconds.
+         * Appears to be currently unused. Should be removed.
+         */
         unsigned int           ns_ctime_age_limit;

Contrary to this comment, ns_ctime_age_limit is still used in mdt_handler.c:mdt_getattr_name_lock() (bugzilla 14910). I'm thinking of of a comment along these lines.

/** 
 * Number of seconds since the file change time after which the 
 * MDT will return an UPDATE lock along with a LOOKUP lock. 
 * This allows the client to start caching negative dentries 
 * for the directory and may save an RPC for a later stat. 
 */ 
unsigned int           ns_ctime_age_limit;

But it's still a bit muddled to me. What is the connection between the change time, the update lock, negative dentries, and why does returning an update lock save an RPC for a stat? How is the value chosen? This may not be the right place to explain all these things; perhaps the LDLM_CTIME_AGE_LIMIT definition would be appropriate, and we could provide a reference here.