Re: Documenting struct function pointers (methods)

[Jani Nikula <jani.nikula@linux.intel.com>]

On Tue, 19 Mar 2019, "Tobin C. Harding" <me@tobin.cc> wrote:
> 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 :)

We use a lot of function pointer members like that the drm subsystem,
and we'd also like to document them similar to functions. Alas, this is
not so much about RST or Sphinx as it is about scripts/kernel-doc that
parses the documentation comments into RST. Would be nice to have this
fixed, but it's not for the faint of heart.

BR,
Jani.


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

-- 
Jani Nikula, Intel Open Source Graphics Center