Re: [PATCH] VFS: fix dentry_create() kernel-doc comment

[Al Viro <viro@zeniv.linux.org.uk>]

On Thu, Dec 18, 2025 at 12:05:00PM +0700, Bagas Sanjaya via B4 Relay wrote:

> @@ -4939,7 +4939,7 @@ EXPORT_SYMBOL(start_creating_user_path);
>  /**
>   * dentry_create - Create and open a file
>   * @path: path to create
> - * @flags: O_ flags
> + * @flags: O\_ flags
>   * @mode: mode bits for new file
>   * @cred: credentials to use
>   *
> @@ -4950,7 +4950,7 @@ EXPORT_SYMBOL(start_creating_user_path);
>   * the new file is to be created. The parent directory and the
>   * negative dentry must reside on the same filesystem instance.
>   *
> - * On success, returns a "struct file *". Otherwise a ERR_PTR
> + * On success, returns a "struct file \*". Otherwise a ERR_PTR
>   * is returned.
>   */

The first one might be borderline sane (I'd probably go for O_... instead
of O_, but whatever); the second is not.

Forget kernel-doc; what is that phrase supposed to mean in the
first place?  "struct file *" (in quotes, for whatever reason)
would presumably imply a value of mentioned type; a function
declared as
struct file *dentry_create(const struct path *path, int flags, umode_t mode,
                           const struct cred *cred)
*always* returns a value of that type, TYVM.

I'm not a native speaker, but I'd suggest something along the lines
of "a pointer to opened file" as replacement for that (without
quote marks, obviously).