Documenting struct function pointers (methods)

Documenting struct function pointers (methods)

[Tobin C. Harding]

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.

Re: Documenting struct function pointers (methods)

[Jani Nikula]

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