[PATCH] jffs2: nodemgmt: fix kernel-doc comments

[PATCH] jffs2: nodemgmt: fix kernel-doc comments

[Randy Dunlap]

Update the end of one sentence where a comment was truncated. (dwmw2)

Fix a bunch of kernel-doc warnings:

nodemgmt.c:72: warning: Function parameter or member 'sumsize' not described in 'jffs2_do_reserve_space'
nodemgmt.c:72: warning: expecting prototype for jffs2_reserve_space(). Prototype was for jffs2_do_reserve_space() instead
nodemgmt.c:76: warning: Function parameter or member 'sumsize' not described in 'jffs2_reserve_space'
nodemgmt.c:76: warning: No description found for return value of 'jffs2_reserve_space'
nodemgmt.c:503: warning: Function parameter or member 'ofs' not described in 'jffs2_add_physical_node_ref'
nodemgmt.c:503: warning: Function parameter or member 'ic' not described in 'jffs2_add_physical_node_ref'
nodemgmt.c:503: warning: Excess function parameter 'new' description in 'jffs2_add_physical_node_ref'
nodemgmt.c:503: warning: No description found for return value of 'jffs2_add_physical_node_ref'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: David Woodhouse <dwmw2@infradead.org>
Cc: Richard Weinberger <richard@nod.at>
Cc: linux-mtd@lists.infradead.org
---
 fs/jffs2/nodemgmt.c |   24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff -- a/fs/jffs2/nodemgmt.c b/fs/jffs2/nodemgmt.c
--- a/fs/jffs2/nodemgmt.c
+++ b/fs/jffs2/nodemgmt.c
@@ -49,28 +49,31 @@ static int jffs2_rp_can_write(struct jff
 	return 0;
 }
 
+static int jffs2_do_reserve_space(struct jffs2_sb_info *c,  uint32_t minsize,
+				  uint32_t *len, uint32_t sumsize);
+
 /**
  *	jffs2_reserve_space - request physical space to write nodes to flash
  *	@c: superblock info
  *	@minsize: Minimum acceptable size of allocation
  *	@len: Returned value of allocation length
  *	@prio: Allocation type - ALLOC_{NORMAL,DELETION}
+ *	@sumsize: summary size requested or JFFS2_SUMMARY_NOSUM_SIZE for no summary
+ *
+ *	Requests a block of physical space on the flash.
  *
- *	Requests a block of physical space on the flash. Returns zero for success
- *	and puts 'len' into the appropriate place, or returns -ENOSPC or other 
- *	error if appropriate. Doesn't return len since that's 
+ *	Returns: %0 for success	and puts 'len' into the appropriate place,
+ *	or returns -ENOSPC or other error if appropriate.
+ *	Doesn't return len since that's already returned in @len.
  *
- *	If it returns zero, jffs2_reserve_space() also downs the per-filesystem
+ *	If it returns %0, jffs2_reserve_space() also downs the per-filesystem
  *	allocation semaphore, to prevent more than one allocation from being
- *	active at any time. The semaphore is later released by jffs2_commit_allocation()
+ *	active at any time. The semaphore is later released by jffs2_commit_allocation().
  *
  *	jffs2_reserve_space() may trigger garbage collection in order to make room
  *	for the requested allocation.
  */
 
-static int jffs2_do_reserve_space(struct jffs2_sb_info *c,  uint32_t minsize,
-				  uint32_t *len, uint32_t sumsize);
-
 int jffs2_reserve_space(struct jffs2_sb_info *c, uint32_t minsize,
 			uint32_t *len, int prio, uint32_t sumsize)
 {
@@ -488,13 +491,16 @@ static int jffs2_do_reserve_space(struct
 /**
  *	jffs2_add_physical_node_ref - add a physical node reference to the list
  *	@c: superblock info
- *	@new: new node reference to add
+ *	@ofs: offset in the block
  *	@len: length of this physical node
+ *	@ic: inode cache pointer
  *
  *	Should only be used to report nodes for which space has been allocated
  *	by jffs2_reserve_space.
  *
  *	Must be called with the alloc_sem held.
+ *
+ *	Returns: pointer to new node on success or -errno code on error
  */
 
 struct jffs2_raw_node_ref *jffs2_add_physical_node_ref(struct jffs2_sb_info *c,

Re: [PATCH] jffs2: nodemgmt: fix kernel-doc comments

[Zhihao Cheng]

在 2023/12/6 1:32, Randy Dunlap 写道:
> Update the end of one sentence where a comment was truncated. (dwmw2)
>
> Fix a bunch of kernel-doc warnings:
>
> nodemgmt.c:72: warning: Function parameter or member 'sumsize' not described in 'jffs2_do_reserve_space'
> nodemgmt.c:72: warning: expecting prototype for jffs2_reserve_space(). Prototype was for jffs2_do_reserve_space() instead
> nodemgmt.c:76: warning: Function parameter or member 'sumsize' not described in 'jffs2_reserve_space'
> nodemgmt.c:76: warning: No description found for return value of 'jffs2_reserve_space'
> nodemgmt.c:503: warning: Function parameter or member 'ofs' not described in 'jffs2_add_physical_node_ref'
> nodemgmt.c:503: warning: Function parameter or member 'ic' not described in 'jffs2_add_physical_node_ref'
> nodemgmt.c:503: warning: Excess function parameter 'new' description in 'jffs2_add_physical_node_ref'
> nodemgmt.c:503: warning: No description found for return value of 'jffs2_add_physical_node_ref'
>
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: David Woodhouse <dwmw2@infradead.org>
> Cc: Richard Weinberger <richard@nod.at>
> Cc: linux-mtd@lists.infradead.org
> ---
>   fs/jffs2/nodemgmt.c |   24 +++++++++++++++---------
>   1 file changed, 15 insertions(+), 9 deletions(-)
Reviewed-by: Zhihao Cheng <chengzhihao1@huawei.com>
> diff -- a/fs/jffs2/nodemgmt.c b/fs/jffs2/nodemgmt.c
> --- a/fs/jffs2/nodemgmt.c
> +++ b/fs/jffs2/nodemgmt.c
> @@ -49,28 +49,31 @@ static int jffs2_rp_can_write(struct jff
>   	return 0;
>   }
>   
> +static int jffs2_do_reserve_space(struct jffs2_sb_info *c,  uint32_t minsize,
> +				  uint32_t *len, uint32_t sumsize);
> +
>   /**
>    *	jffs2_reserve_space - request physical space to write nodes to flash
>    *	@c: superblock info
>    *	@minsize: Minimum acceptable size of allocation
>    *	@len: Returned value of allocation length
>    *	@prio: Allocation type - ALLOC_{NORMAL,DELETION}
> + *	@sumsize: summary size requested or JFFS2_SUMMARY_NOSUM_SIZE for no summary
> + *
> + *	Requests a block of physical space on the flash.
>    *
> - *	Requests a block of physical space on the flash. Returns zero for success
> - *	and puts 'len' into the appropriate place, or returns -ENOSPC or other
> - *	error if appropriate. Doesn't return len since that's
> + *	Returns: %0 for success	and puts 'len' into the appropriate place,
> + *	or returns -ENOSPC or other error if appropriate.
> + *	Doesn't return len since that's already returned in @len.
>    *
> - *	If it returns zero, jffs2_reserve_space() also downs the per-filesystem
> + *	If it returns %0, jffs2_reserve_space() also downs the per-filesystem
>    *	allocation semaphore, to prevent more than one allocation from being
> - *	active at any time. The semaphore is later released by jffs2_commit_allocation()
> + *	active at any time. The semaphore is later released by jffs2_commit_allocation().
>    *
>    *	jffs2_reserve_space() may trigger garbage collection in order to make room
>    *	for the requested allocation.
>    */
>   
> -static int jffs2_do_reserve_space(struct jffs2_sb_info *c,  uint32_t minsize,
> -				  uint32_t *len, uint32_t sumsize);
> -
>   int jffs2_reserve_space(struct jffs2_sb_info *c, uint32_t minsize,
>   			uint32_t *len, int prio, uint32_t sumsize)
>   {
> @@ -488,13 +491,16 @@ static int jffs2_do_reserve_space(struct
>   /**
>    *	jffs2_add_physical_node_ref - add a physical node reference to the list
>    *	@c: superblock info
> - *	@new: new node reference to add
> + *	@ofs: offset in the block
>    *	@len: length of this physical node
> + *	@ic: inode cache pointer
>    *
>    *	Should only be used to report nodes for which space has been allocated
>    *	by jffs2_reserve_space.
>    *
>    *	Must be called with the alloc_sem held.
> + *
> + *	Returns: pointer to new node on success or -errno code on error
>    */
>   
>   struct jffs2_raw_node_ref *jffs2_add_physical_node_ref(struct jffs2_sb_info *c,
>
> ______________________________________________________
> Linux MTD discussion mailing list
> http://lists.infradead.org/mailman/listinfo/linux-mtd/
> .

Re: [PATCH] jffs2: nodemgmt: fix kernel-doc comments

[Jeff Johnson]

On 12/5/23 09:32, Randy Dunlap wrote:
> Update the end of one sentence where a comment was truncated. (dwmw2)
> 
> Fix a bunch of kernel-doc warnings:
> 
> nodemgmt.c:72: warning: Function parameter or member 'sumsize' not described in 'jffs2_do_reserve_space'
> nodemgmt.c:72: warning: expecting prototype for jffs2_reserve_space(). Prototype was for jffs2_do_reserve_space() instead
> nodemgmt.c:76: warning: Function parameter or member 'sumsize' not described in 'jffs2_reserve_space'
> nodemgmt.c:76: warning: No description found for return value of 'jffs2_reserve_space'
> nodemgmt.c:503: warning: Function parameter or member 'ofs' not described in 'jffs2_add_physical_node_ref'
> nodemgmt.c:503: warning: Function parameter or member 'ic' not described in 'jffs2_add_physical_node_ref'
> nodemgmt.c:503: warning: Excess function parameter 'new' description in 'jffs2_add_physical_node_ref'
> nodemgmt.c:503: warning: No description found for return value of 'jffs2_add_physical_node_ref'
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: David Woodhouse <dwmw2@infradead.org>
> Cc: Richard Weinberger <richard@nod.at>
> Cc: linux-mtd@lists.infradead.org

I was about to submit a patch for these, but then checked lore and saw 
this was posted a while back, but so far not merged. Hopefully my R-B 
will provide some momentum

Reviewed-by: Jeff Johnson <quic_jjohnson@quicinc.com>