- * Create a volatile file and open it for write:
- * - file is created as a standard file in the directory
- * - file does not appears in directory and directory mtime does not change
- * - file is removed at close
- * - file modes are rw-------, if user wants another one it must use fchmod()
- * \param directory Directory where the file is created
- * \param idx MDT index on which the file is created
- * \param open_flags Standard open flags
+ * Create a file without any name open it for read/write
+ *
+ * - file is created as if it were a standard file in the given \a directory
+ * - file does not appear in \a directory and mtime does not change because
+ * the filename is handled specially by the Lustre MDS.
+ * - file is removed at final close
+ * - file modes are rw------- since it doesn't make sense to have a read-only
+ * or write-only file that cannot be opened again.
+ * - if user wants another mode it must use fchmod() on the open file, no
+ * security problems arise because it cannot be opened by another process.
+ *
+ * \param[in] directory directory from which to inherit layout/MDT idx
+ * \param[in] idx MDT index on which the file is created,
+ * \a idx == -1 means no specific MDT is requested
+ * \param[in] open_flags standard open(2) flags