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

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

[Bagas Sanjaya via B4 Relay]

From: Bagas Sanjaya <bagasdotme@gmail.com>

Sphinx reports htmldocs warnings:

Documentation/filesystems/api-summary:56: fs/namei.c:4952: WARNING: Inline emphasis start-string without end-string. [docutils]
Documentation/filesystems/api-summary:56: fs/namei.c:4942: ERROR: Unknown target name: "o". [docutils]

Fix them by escaping trailing underscore and wildcard.

Fixes: 977de00dfcf87e ("VFS: move dentry_create() from fs/open.c to fs/namei.c")
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/linux-next/20251216115252.709078e8@canb.auug.org.au/
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
Sphinx reports htmldocs warnings:

Documentation/filesystems/api-summary:56: fs/namei.c:4952: WARNING: Inline emphasis start-string without end-string. [docutils]
Documentation/filesystems/api-summary:56: fs/namei.c:4942: ERROR: Unknown target name: "o". [docutils]

Fix them by escaping trailing underscore and wildcard.
---
 fs/namei.c | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/fs/namei.c b/fs/namei.c
index aefb21bc0944e3..d575d671b4f960 100644
--- a/fs/namei.c
+++ b/fs/namei.c
@@ -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.
  */
 struct file *dentry_create(struct path *path, int flags, umode_t mode,

---
base-commit: 981be27a72d163610e8e1c342373930bae80ac99
change-id: 20251218-dentry-inline-4091feeae685

Best regards,
-- 
Bagas Sanjaya <bagasdotme@gmail.com>

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

[Al Viro]

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).

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

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 882 bytes --]

On Thu, Dec 18, 2025 at 06:10:56AM +0000, Al Viro wrote:
> The first one might be borderline sane (I'd probably go for O_... instead
> of O_, but whatever); the second is not.

Or O_\* flags?

> 
> 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).

Ack. Will apply your suggestions in v2.

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]