From 4dc3b16ba18c0f967ad100c52fa65b01a4f76ff0 Mon Sep 17 00:00:00 2001 From: Pavel Pisa Date: Sun, 1 May 2005 08:59:25 -0700 Subject: [PATCH] DocBook: changes and extensions to the kernel documentation I have recompiled Linux kernel 2.6.11.5 documentation for me and our university students again. The documentation could be extended for more sources which are equipped by structured comments for recent 2.6 kernels. I have tried to proceed with that task. I have done that more times from 2.6.0 time and it gets boring to do same changes again and again. Linux kernel compiles after changes for i386 and ARM targets. I have added references to some more files into kernel-api book, I have added some section names as well. So please, check that changes do not break something and that categories are not too much skewed. I have changed kernel-doc to accept "fastcall" and "asmlinkage" words reserved by kernel convention. Most of the other changes are modifications in the comments to make kernel-doc happy, accept some parameters description and do not bail out on errors. Changed to @pid in the description, moved some #ifdef before comments to correct function to comments bindings, etc. You can see result of the modified documentation build at http://cmp.felk.cvut.cz/~pisa/linux/lkdb-2.6.11.tar.gz Some more sources are ready to be included into kernel-doc generated documentation. Sources has been added into kernel-api for now. Some more section names added and probably some more chaos introduced as result of quick cleanup work. Signed-off-by: Pavel Pisa Signed-off-by: Martin Waitz Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- include/linux/fs.h | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'include/linux/fs.h') diff --git a/include/linux/fs.h b/include/linux/fs.h index 5df687d940fa..3f825b085c8d 100644 --- a/include/linux/fs.h +++ b/include/linux/fs.h @@ -1053,12 +1053,12 @@ static inline void file_accessed(struct file *file) int sync_inode(struct inode *inode, struct writeback_control *wbc); /** - * &export_operations - for nfsd to communicate with file systems - * decode_fh: decode a file handle fragment and return a &struct dentry - * encode_fh: encode a file handle fragment from a dentry - * get_name: find the name for a given inode in a given directory - * get_parent: find the parent of a given directory - * get_dentry: find a dentry for the inode given a file handle sub-fragment + * struct export_operations - for nfsd to communicate with file systems + * @decode_fh: decode a file handle fragment and return a &struct dentry + * @encode_fh: encode a file handle fragment from a dentry + * @get_name: find the name for a given inode in a given directory + * @get_parent: find the parent of a given directory + * @get_dentry: find a dentry for the inode given a file handle sub-fragment * * Description: * The export_operations structure provides a means for nfsd to communicate -- cgit v1.2.2 From 67be2dd1bace0ec7ce2dbc1bba3f8df3d7be597e Mon Sep 17 00:00:00 2001 From: Martin Waitz Date: Sun, 1 May 2005 08:59:26 -0700 Subject: [PATCH] DocBook: fix some descriptions Some KernelDoc descriptions are updated to match the current code. No code changes. Signed-off-by: Martin Waitz Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- include/linux/fs.h | 100 ++++++++++++++++++++++++++++------------------------- 1 file changed, 52 insertions(+), 48 deletions(-) (limited to 'include/linux/fs.h') diff --git a/include/linux/fs.h b/include/linux/fs.h index 3f825b085c8d..4edba067a717 100644 --- a/include/linux/fs.h +++ b/include/linux/fs.h @@ -1065,71 +1065,75 @@ int sync_inode(struct inode *inode, struct writeback_control *wbc); * with a particular exported file system - particularly enabling nfsd and * the filesystem to co-operate when dealing with file handles. * - * export_operations contains two basic operation for dealing with file handles, - * decode_fh() and encode_fh(), and allows for some other operations to be defined - * which standard helper routines use to get specific information from the - * filesystem. + * export_operations contains two basic operation for dealing with file + * handles, decode_fh() and encode_fh(), and allows for some other + * operations to be defined which standard helper routines use to get + * specific information from the filesystem. * * nfsd encodes information use to determine which filesystem a filehandle - * applies to in the initial part of the file handle. The remainder, termed a - * file handle fragment, is controlled completely by the filesystem. - * The standard helper routines assume that this fragment will contain one or two - * sub-fragments, one which identifies the file, and one which may be used to - * identify the (a) directory containing the file. + * applies to in the initial part of the file handle. The remainder, termed + * a file handle fragment, is controlled completely by the filesystem. The + * standard helper routines assume that this fragment will contain one or + * two sub-fragments, one which identifies the file, and one which may be + * used to identify the (a) directory containing the file. * * In some situations, nfsd needs to get a dentry which is connected into a - * specific part of the file tree. To allow for this, it passes the function - * acceptable() together with a @context which can be used to see if the dentry - * is acceptable. As there can be multiple dentrys for a given file, the filesystem - * should check each one for acceptability before looking for the next. As soon - * as an acceptable one is found, it should be returned. + * specific part of the file tree. To allow for this, it passes the + * function acceptable() together with a @context which can be used to see + * if the dentry is acceptable. As there can be multiple dentrys for a + * given file, the filesystem should check each one for acceptability before + * looking for the next. As soon as an acceptable one is found, it should + * be returned. * * decode_fh: - * @decode_fh is given a &struct super_block (@sb), a file handle fragment (@fh, @fh_len) - * and an acceptability testing function (@acceptable, @context). It should return - * a &struct dentry which refers to the same file that the file handle fragment refers - * to, and which passes the acceptability test. If it cannot, it should return - * a %NULL pointer if the file was found but no acceptable &dentries were available, or - * a %ERR_PTR error code indicating why it couldn't be found (e.g. %ENOENT or %ENOMEM). + * @decode_fh is given a &struct super_block (@sb), a file handle fragment + * (@fh, @fh_len) and an acceptability testing function (@acceptable, + * @context). It should return a &struct dentry which refers to the same + * file that the file handle fragment refers to, and which passes the + * acceptability test. If it cannot, it should return a %NULL pointer if + * the file was found but no acceptable &dentries were available, or a + * %ERR_PTR error code indicating why it couldn't be found (e.g. %ENOENT or + * %ENOMEM). * * encode_fh: - * @encode_fh should store in the file handle fragment @fh (using at most @max_len bytes) - * information that can be used by @decode_fh to recover the file refered to by the - * &struct dentry @de. If the @connectable flag is set, the encode_fh() should store - * sufficient information so that a good attempt can be made to find not only - * the file but also it's place in the filesystem. This typically means storing - * a reference to de->d_parent in the filehandle fragment. - * encode_fh() should return the number of bytes stored or a negative error code - * such as %-ENOSPC + * @encode_fh should store in the file handle fragment @fh (using at most + * @max_len bytes) information that can be used by @decode_fh to recover the + * file refered to by the &struct dentry @de. If the @connectable flag is + * set, the encode_fh() should store sufficient information so that a good + * attempt can be made to find not only the file but also it's place in the + * filesystem. This typically means storing a reference to de->d_parent in + * the filehandle fragment. encode_fh() should return the number of bytes + * stored or a negative error code such as %-ENOSPC * * get_name: - * @get_name should find a name for the given @child in the given @parent directory. - * The name should be stored in the @name (with the understanding that it is already - * pointing to a a %NAME_MAX+1 sized buffer. get_name() should return %0 on success, - * a negative error code or error. - * @get_name will be called without @parent->i_sem held. + * @get_name should find a name for the given @child in the given @parent + * directory. The name should be stored in the @name (with the + * understanding that it is already pointing to a a %NAME_MAX+1 sized + * buffer. get_name() should return %0 on success, a negative error code + * or error. @get_name will be called without @parent->i_sem held. * * get_parent: - * @get_parent should find the parent directory for the given @child which is also - * a directory. In the event that it cannot be found, or storage space cannot be - * allocated, a %ERR_PTR should be returned. + * @get_parent should find the parent directory for the given @child which + * is also a directory. In the event that it cannot be found, or storage + * space cannot be allocated, a %ERR_PTR should be returned. * * get_dentry: - * Given a &super_block (@sb) and a pointer to a file-system specific inode identifier, - * possibly an inode number, (@inump) get_dentry() should find the identified inode and - * return a dentry for that inode. - * Any suitable dentry can be returned including, if necessary, a new dentry created - * with d_alloc_root. The caller can then find any other extant dentrys by following the - * d_alias links. If a new dentry was created using d_alloc_root, DCACHE_NFSD_DISCONNECTED - * should be set, and the dentry should be d_rehash()ed. + * Given a &super_block (@sb) and a pointer to a file-system specific inode + * identifier, possibly an inode number, (@inump) get_dentry() should find + * the identified inode and return a dentry for that inode. Any suitable + * dentry can be returned including, if necessary, a new dentry created with + * d_alloc_root. The caller can then find any other extant dentrys by + * following the d_alias links. If a new dentry was created using + * d_alloc_root, DCACHE_NFSD_DISCONNECTED should be set, and the dentry + * should be d_rehash()ed. * - * If the inode cannot be found, either a %NULL pointer or an %ERR_PTR code can be returned. - * The @inump will be whatever was passed to nfsd_find_fh_dentry() in either the - * @obj or @parent parameters. + * If the inode cannot be found, either a %NULL pointer or an %ERR_PTR code + * can be returned. The @inump will be whatever was passed to + * nfsd_find_fh_dentry() in either the @obj or @parent parameters. * * Locking rules: - * get_parent is called with child->d_inode->i_sem down - * get_name is not (which is possibly inconsistent) + * get_parent is called with child->d_inode->i_sem down + * get_name is not (which is possibly inconsistent) */ struct export_operations { -- cgit v1.2.2