Documenting struct function pointers (methods)

["Tobin C. Harding" <me@xxxxxxxx>]

Hi,

Is documenting 'methods' i.e. function pointers in structs like 'struct
file_operations' something that we do anywhere?  Is this handled by RST?
Is it something that has been discussed already?

I'm in the process of trying to grok the dcache and update the docs.
For each function pointer I'm reading various implementations and trying
to work out what the method is supposed to do.  Surely this is a good
candidate for improving kernel documentation in order to help devs come
up to speed more quickly?

An example from include/linux/fs.h (adding docstring comments to struct
file_system_type).  This is _not_ handled correctly by Sphinx, is there
a way to do this?  Or are hard-core hackers going to scream that this is
too much documentation :)


/**
 * struct file_system_type
 * @name: Name of the filesystem type, such as "ext2", "iso9660",
 *        "msdos" and so on.
 * @fs_flags: Various flags (i.e. FS_REQUIRES_DEV, FS_NO_DCACHE, etc.).
 * ...
 */
struct file_system_type {
       [snip]
	const struct fs_parameter_description *parameters;
	/**
	 * @mount: The method to call when a new instance of this
	 *         filesystem should be mounted.
	 *
	 * The mount() method has the following arguments:
	 * @fs_type: Describes the filesystem, partly initialized by the
	 *           specific filesystem code.
	 * @flags: Mount flags.
	 * @dev_name: The device name we are mounting.
	 * @data: Arbitrary mount options, usually comes as an ASCII
	 *        string (see "Mount Options" section).
	 */
	struct dentry *(*mount) (struct file_system_type *fs_type, int flags,
				 const char *dev_name, void *data);
	void (*kill_sb) (struct super_block *);


thanks,
Tobin.