[PATCH 0/4] exportfs: Some kernel-doc fixes

[PATCH 0/4] exportfs: Some kernel-doc fixes

[André Almeida]

This short series removes some duplicated documentation and address some
kernel-doc issues:

WARNING: ../include/linux/exportfs.h:289 struct member 'get_uuid' not described in 'export_operations'
WARNING: ../include/linux/exportfs.h:289 struct member 'map_blocks' not described in 'export_operations'
WARNING: ../include/linux/exportfs.h:289 struct member 'commit_blocks' not described in 'export_operations'
WARNING: ../include/linux/exportfs.h:289 struct member 'permission' not described in 'export_operations'
WARNING: ../include/linux/exportfs.h:289 struct member 'open' not described in 'export_operations'
WARNING: ../include/linux/exportfs.h:289 struct member 'flags' not described in 'export_operations'

---
André Almeida (4):
      exportfs: Fix kernel-doc output for get_name()
      exportfs: Mark struct export_operations functions at kernel-doc
      exportfs: Complete kernel-doc for struct export_operations
      docs: exportfs: Use source code struct documentation

 Documentation/filesystems/nfs/exporting.rst | 42 ++++-------------------------
 include/linux/exportfs.h                    | 33 ++++++++++++++++-------
 2 files changed, 28 insertions(+), 47 deletions(-)
---
base-commit: 9c7ef209cd0f7c1a92ed61eed3e835d6e4abc66c
change-id: 20260112-tonyk-fs_uuid-973d5fdfc76f

Best regards,
-- 
André Almeida <andrealmeid@igalia.com>

[PATCH 1/4] exportfs: Fix kernel-doc output for get_name()

[André Almeida]

Without a space between %NAME_MAX and the plus sign, kernel-doc will
output ``NAME_MAX``+1, which scapes the last backtick and make Sphinx
format a much larger string as monospaced text.

Signed-off-by: André Almeida <andrealmeid@igalia.com>
---
 include/linux/exportfs.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/exportfs.h b/include/linux/exportfs.h
index f0cf2714ec52..599ea86363e1 100644
--- a/include/linux/exportfs.h
+++ b/include/linux/exportfs.h
@@ -234,7 +234,7 @@ struct handle_to_path_ctx {
  * get_name:
  *    @get_name should find a name for the given @child in the given @parent
  *    directory.  The name should be stored in the @name (with the
- *    understanding that it is already pointing to a %NAME_MAX+1 sized
+ *    understanding that it is already pointing to a %NAME_MAX + 1 sized
  *    buffer.   get_name() should return %0 on success, a negative error code
  *    or error.  @get_name will be called without @parent->i_rwsem held.
  *

-- 
2.52.0

[PATCH 2/4] exportfs: Mark struct export_operations functions at kernel-doc

[André Almeida]

Adding a `@` before the function names make then recognizable as
kernel-docs, so they get correctly rendered in the documentation.

Even if they are already marked with `@` in the short one-line summary,
the kernel-docs will correctly favor the more detailed definition here.

Signed-off-by: André Almeida <andrealmeid@igalia.com>
---
Should I just remove the short descriptions?
---
 include/linux/exportfs.h | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/include/linux/exportfs.h b/include/linux/exportfs.h
index 599ea86363e1..bed370b9f906 100644
--- a/include/linux/exportfs.h
+++ b/include/linux/exportfs.h
@@ -203,7 +203,7 @@ struct handle_to_path_ctx {
  * See Documentation/filesystems/nfs/exporting.rst for details on how to use
  * this interface correctly.
  *
- * encode_fh:
+ * @encode_fh:
  *    @encode_fh should store in the file handle fragment @fh (using at most
  *    @max_len bytes) information that can be used by @decode_fh to recover the
  *    file referred to by the &struct dentry @de.  If @flag has CONNECTABLE bit
@@ -215,7 +215,7 @@ struct handle_to_path_ctx {
  *    greater than @max_len*4 bytes). On error @max_len contains the minimum
  *    size(in 4 byte unit) needed to encode the file handle.
  *
- * fh_to_dentry:
+ * @fh_to_dentry:
  *    @fh_to_dentry is given a &struct super_block (@sb) and a file handle
  *    fragment (@fh, @fh_len). It should return a &struct dentry which refers
  *    to the same file that the file handle fragment refers to.  If it cannot,
@@ -227,29 +227,29 @@ struct handle_to_path_ctx {
  *    created with d_alloc_root.  The caller can then find any other extant
  *    dentries by following the d_alias links.
  *
- * fh_to_parent:
+ * @fh_to_parent:
  *    Same as @fh_to_dentry, except that it returns a pointer to the parent
  *    dentry if it was encoded into the filehandle fragment by @encode_fh.
  *
- * get_name:
+ * @get_name:
  *    @get_name should find a name for the given @child in the given @parent
  *    directory.  The name should be stored in the @name (with the
  *    understanding that it is already pointing to a %NAME_MAX + 1 sized
  *    buffer.   get_name() should return %0 on success, a negative error code
  *    or error.  @get_name will be called without @parent->i_rwsem held.
  *
- * get_parent:
+ * @get_parent:
  *    @get_parent should find the parent directory for the given @child which
  *    is also a directory.  In the event that it cannot be found, or storage
  *    space cannot be allocated, a %ERR_PTR should be returned.
  *
- * permission:
+ * @permission:
  *    Allow filesystems to specify a custom permission function.
  *
- * open:
+ * @open:
  *    Allow filesystems to specify a custom open function.
  *
- * commit_metadata:
+ * @commit_metadata:
  *    @commit_metadata should commit metadata changes to stable storage.
  *
  * Locking rules:

-- 
2.52.0

[PATCH 3/4] exportfs: Complete kernel-doc for struct export_operations

[André Almeida]

Write down the missing members definitions for struct export_operations,
using as a reference the commit messages that created the members.

Signed-off-by: André Almeida <andrealmeid@igalia.com>
---
 include/linux/exportfs.h | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/include/linux/exportfs.h b/include/linux/exportfs.h
index bed370b9f906..262e24d83313 100644
--- a/include/linux/exportfs.h
+++ b/include/linux/exportfs.h
@@ -201,7 +201,7 @@ struct handle_to_path_ctx {
  * @commit_metadata: commit metadata changes to stable storage
  *
  * See Documentation/filesystems/nfs/exporting.rst for details on how to use
- * this interface correctly.
+ * this interface correctly and the definition of the flags.
  *
  * @encode_fh:
  *    @encode_fh should store in the file handle fragment @fh (using at most
@@ -252,6 +252,19 @@ struct handle_to_path_ctx {
  * @commit_metadata:
  *    @commit_metadata should commit metadata changes to stable storage.
  *
+ * @get_uuid:
+ *    Get a filesystem unique signature exposed to clients.
+ *
+ * @map_blocks:
+ *    Map and, if necessary, allocate blocks for a layout.
+ *
+ * @commit_blocks:
+ *    Commit blocks in a layout once the client is done with them.
+ *
+ * @flags:
+ *    Allows the filesystem to communicate to nfsd that it may want to do things
+ *    differently when dealing with it.
+ *
  * Locking rules:
  *    get_parent is called with child->d_inode->i_rwsem down
  *    get_name is not (which is possibly inconsistent)

-- 
2.52.0

[PATCH 4/4] docs: exportfs: Use source code struct documentation

[André Almeida]

Instead of duplicating struct export_operations documentation in both
ReST file and in the C source code, just use the kernel-doc in the docs.

While here, make the sentence preceding the paragraph less redundant.

Signed-off-by: André Almeida <andrealmeid@igalia.com>
---
 Documentation/filesystems/nfs/exporting.rst | 42 ++++-------------------------
 1 file changed, 5 insertions(+), 37 deletions(-)

diff --git a/Documentation/filesystems/nfs/exporting.rst b/Documentation/filesystems/nfs/exporting.rst
index de64d2d002a2..a01d9b9b5bc3 100644
--- a/Documentation/filesystems/nfs/exporting.rst
+++ b/Documentation/filesystems/nfs/exporting.rst
@@ -119,43 +119,11 @@ For a filesystem to be exportable it must:
 
 A file system implementation declares that instances of the filesystem
 are exportable by setting the s_export_op field in the struct
-super_block.  This field must point to a "struct export_operations"
-struct which has the following members:
-
-  encode_fh (mandatory)
-    Takes a dentry and creates a filehandle fragment which may later be used
-    to find or create a dentry for the same object.
-
-  fh_to_dentry (mandatory)
-    Given a filehandle fragment, this should find the implied object and
-    create a dentry for it (possibly with d_obtain_alias).
-
-  fh_to_parent (optional but strongly recommended)
-    Given a filehandle fragment, this should find the parent of the
-    implied object and create a dentry for it (possibly with
-    d_obtain_alias).  May fail if the filehandle fragment is too small.
-
-  get_parent (optional but strongly recommended)
-    When given a dentry for a directory, this should return  a dentry for
-    the parent.  Quite possibly the parent dentry will have been allocated
-    by d_alloc_anon.  The default get_parent function just returns an error
-    so any filehandle lookup that requires finding a parent will fail.
-    ->lookup("..") is *not* used as a default as it can leave ".." entries
-    in the dcache which are too messy to work with.
-
-  get_name (optional)
-    When given a parent dentry and a child dentry, this should find a name
-    in the directory identified by the parent dentry, which leads to the
-    object identified by the child dentry.  If no get_name function is
-    supplied, a default implementation is provided which uses vfs_readdir
-    to find potential names, and matches inode numbers to find the correct
-    match.
-
-  flags
-    Some filesystems may need to be handled differently than others. The
-    export_operations struct also includes a flags field that allows the
-    filesystem to communicate such information to nfsd. See the Export
-    Operations Flags section below for more explanation.
+super_block.  This field must point to a struct export_operations
+which has the following members:
+
+.. kernel-doc:: include/linux/exportfs.h
+   :identifiers: struct export_operations
 
 A filehandle fragment consists of an array of 1 or more 4byte words,
 together with a one byte "type".

-- 
2.52.0

Re: [PATCH 0/4] exportfs: Some kernel-doc fixes

[Chuck Lever]

On Mon, Jan 12, 2026, at 8:51 PM, André Almeida wrote:
> This short series removes some duplicated documentation and address some
> kernel-doc issues:
>
> WARNING: ../include/linux/exportfs.h:289 struct member 'get_uuid' not 
> described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'map_blocks' not 
> described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'commit_blocks' 
> not described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'permission' not 
> described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'open' not 
> described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'flags' not 
> described in 'export_operations'
>
> ---
> André Almeida (4):
>       exportfs: Fix kernel-doc output for get_name()
>       exportfs: Mark struct export_operations functions at kernel-doc
>       exportfs: Complete kernel-doc for struct export_operations
>       docs: exportfs: Use source code struct documentation
>
>  Documentation/filesystems/nfs/exporting.rst | 42 ++++-------------------------
>  include/linux/exportfs.h                    | 33 ++++++++++++++++-------
>  2 files changed, 28 insertions(+), 47 deletions(-)
> ---
> base-commit: 9c7ef209cd0f7c1a92ed61eed3e835d6e4abc66c
> change-id: 20260112-tonyk-fs_uuid-973d5fdfc76f
>
> Best regards,
> -- 
> André Almeida <andrealmeid@igalia.com>

Reviewed-by: Chuck Lever <chuck.lever@oracle.com>


-- 
Chuck Lever

Re: [PATCH 0/4] exportfs: Some kernel-doc fixes

[Christian Brauner]

On Mon, 12 Jan 2026 22:51:23 -0300, André Almeida wrote:
> This short series removes some duplicated documentation and address some
> kernel-doc issues:
> 
> 

Applied to the vfs-7.0.misc branch of the vfs/vfs.git tree.
Patches in the vfs-7.0.misc branch should appear in linux-next soon.

Please report any outstanding bugs that were missed during review in a
new review to the original patch series allowing us to drop it.

It's encouraged to provide Acked-bys and Reviewed-bys even though the
patch has now been applied. If possible patch trailers will be updated.

Note that commit hashes shown below are subject to change due to rebase,
trailer updates or similar. If in doubt, please check the listed branch.

tree:   https://git.kernel.org/pub/scm/linux/kernel/git/vfs/vfs.git
branch: vfs-7.0.misc

[1/4] exportfs: Fix kernel-doc output for get_name()
      https://git.kernel.org/vfs/vfs/c/c9ae970f7c11
[2/4] exportfs: Mark struct export_operations functions at kernel-doc
      https://git.kernel.org/vfs/vfs/c/69639fccd6e3
[3/4] exportfs: Complete kernel-doc for struct export_operations
      https://git.kernel.org/vfs/vfs/c/66982f431798
[4/4] docs: exportfs: Use source code struct documentation
      https://git.kernel.org/vfs/vfs/c/4e9076eaa1a9

Re: [PATCH 0/4] exportfs: Some kernel-doc fixes

[Jeff Layton]

On Mon, 2026-01-12 at 22:51 -0300, André Almeida wrote:
> This short series removes some duplicated documentation and address some
> kernel-doc issues:
> 
> WARNING: ../include/linux/exportfs.h:289 struct member 'get_uuid' not described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'map_blocks' not described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'commit_blocks' not described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'permission' not described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'open' not described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'flags' not described in 'export_operations'
> 
> ---
> André Almeida (4):
>       exportfs: Fix kernel-doc output for get_name()
>       exportfs: Mark struct export_operations functions at kernel-doc
>       exportfs: Complete kernel-doc for struct export_operations
>       docs: exportfs: Use source code struct documentation
> 
>  Documentation/filesystems/nfs/exporting.rst | 42 ++++-------------------------
>  include/linux/exportfs.h                    | 33 ++++++++++++++++-------
>  2 files changed, 28 insertions(+), 47 deletions(-)
> ---
> base-commit: 9c7ef209cd0f7c1a92ed61eed3e835d6e4abc66c
> change-id: 20260112-tonyk-fs_uuid-973d5fdfc76f
> 
> Best regards,

LGTM:

Reviewed-by: Jeff Layton <jlayton@kernel.org>

Re: [PATCH 0/4] exportfs: Some kernel-doc fixes

[Randy Dunlap]

On 1/12/26 5:51 PM, André Almeida wrote:
> This short series removes some duplicated documentation and address some
> kernel-doc issues:
> 
> WARNING: ../include/linux/exportfs.h:289 struct member 'get_uuid' not described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'map_blocks' not described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'commit_blocks' not described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'permission' not described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'open' not described in 'export_operations'
> WARNING: ../include/linux/exportfs.h:289 struct member 'flags' not described in 'export_operations'

For all 4 patches:

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks!

> ---
> André Almeida (4):
>       exportfs: Fix kernel-doc output for get_name()
>       exportfs: Mark struct export_operations functions at kernel-doc
>       exportfs: Complete kernel-doc for struct export_operations
>       docs: exportfs: Use source code struct documentation
> 
>  Documentation/filesystems/nfs/exporting.rst | 42 ++++-------------------------
>  include/linux/exportfs.h                    | 33 ++++++++++++++++-------
>  2 files changed, 28 insertions(+), 47 deletions(-)
> ---
> base-commit: 9c7ef209cd0f7c1a92ed61eed3e835d6e4abc66c
> change-id: 20260112-tonyk-fs_uuid-973d5fdfc76f
> 
> Best regards,

-- 
~Randy