[PATCH] scatterlist: fix extraneous '@'-sign kernel-doc notation

[PATCH] scatterlist: fix extraneous '@'-sign kernel-doc notation

[Randy Dunlap]

Using "@argname@" in kernel-doc produces "argname****" (with "argname"
in bold) in the generated html output, so use the expected kernel-doc
notation of just "@argname" instead.

"Fixes:" are added in case Matthew's patch [1] is backported.

Fixes: 0db9299f48eb ("SG: Move functions to lib/scatterlist.c and add sg chaining allocator helpers")
Fixes: 8d1d4b538bb1 ("scatterlist: inline sg_next()")
Fixes: 18dabf473e15 ("Change table chaining layout")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Matthew Wilcox <willy@infradead.org>
Cc: linux-doc@vger.kernel.org

[1]: https://lore.kernel.org/linux-doc/3bc4e779-7a79-42c1-8867-024f643a22fc@infradead.org/T/#m5d2bd9d21fb34f297aa4e7db069f09bc27b89007
---

 include/linux/scatterlist.h |    4 ++--
 lib/scatterlist.c           |    8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

--- linux-next-20250604.orig/include/linux/scatterlist.h
+++ linux-next-20250604/include/linux/scatterlist.h
@@ -99,7 +99,7 @@ static inline bool sg_is_last(struct sca
  * @sg:		The current sg entry
  *
  * Description:
- *   Usually the next entry will be @sg@ + 1, but if this sg element is part
+ *   Usually the next entry will be @sg + 1, but if this sg element is part
  *   of a chained scatterlist, it could jump to the start of a new
  *   scatterlist array.
  *
@@ -254,7 +254,7 @@ static inline void __sg_chain(struct sca
  * @sgl:	Second scatterlist
  *
  * Description:
- *   Links @prv@ and @sgl@ together, to form a longer scatterlist.
+ *   Links @prv and @sgl together, to form a longer scatterlist.
  *
  **/
 static inline void sg_chain(struct scatterlist *prv, unsigned int prv_nents,
--- linux-next-20250604.orig/lib/scatterlist.c
+++ linux-next-20250604/lib/scatterlist.c
@@ -73,9 +73,9 @@ EXPORT_SYMBOL(sg_nents_for_len);
  *   Should only be used casually, it (currently) scans the entire list
  *   to get the last entry.
  *
- *   Note that the @sgl@ pointer passed in need not be the first one,
- *   the important bit is that @nents@ denotes the number of entries that
- *   exist from @sgl@.
+ *   Note that the @sgl pointer passed in need not be the first one,
+ *   the important bit is that @nents denotes the number of entries that
+ *   exist from @sgl.
  *
  **/
 struct scatterlist *sg_last(struct scatterlist *sgl, unsigned int nents)
@@ -345,7 +345,7 @@ EXPORT_SYMBOL(__sg_alloc_table);
  * @gfp_mask:	GFP allocation mask
  *
  *  Description:
- *    Allocate and initialize an sg table. If @nents@ is larger than
+ *    Allocate and initialize an sg table. If @nents is larger than
  *    SG_MAX_SINGLE_ALLOC a chained sg table will be setup.
  *
  **/

Re: [PATCH] scatterlist: fix extraneous '@'-sign kernel-doc notation

[Matthew Wilcox]

On Wed, Jun 04, 2025 at 05:23:37PM -0700, Randy Dunlap wrote:
> Using "@argname@" in kernel-doc produces "argname****" (with "argname"
> in bold) in the generated html output, so use the expected kernel-doc
> notation of just "@argname" instead.
> 
> "Fixes:" are added in case Matthew's patch [1] is backported.

Thanks!  I only skimmed the built docs and didn't notice this ... oddity.

> Fixes: 0db9299f48eb ("SG: Move functions to lib/scatterlist.c and add sg chaining allocator helpers")
> Fixes: 8d1d4b538bb1 ("scatterlist: inline sg_next()")
> Fixes: 18dabf473e15 ("Change table chaining layout")
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Andrew Morton <akpm@linux-foundation.org>
> Cc: Matthew Wilcox <willy@infradead.org>
> Cc: linux-doc@vger.kernel.org

Reviewed-by: Matthew Wilcox (Oracle) <willy@infradead.org>