From: Alejandro Colomar <alx@kernel.org>
Date: Mon, 10 Feb 2025 13:49:53 +0000 (+0100)
Subject: lib/string/: Compact documentation
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=96de8be2ae542eb22e63c90b9bc447594b5497c0;p=thirdparty%2Fshadow.git

lib/string/: Compact documentation

In the case of [v]snprintf_(), anticipate the rename in the next commit.

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

diff --git a/lib/string/sprintf/snprintf.h b/lib/string/sprintf/snprintf.h
index 9d373d940..bc55b9ba9 100644
--- a/lib/string/sprintf/snprintf.h
+++ b/lib/string/sprintf/snprintf.h
@@ -25,11 +25,14 @@
 )
 
 
+// stprintf - string truncate print formatted
 format_attr(printf, 3, 4)
-inline int snprintf_(char *restrict s, ssize_t size, const char *restrict fmt, ...);
+inline int snprintf_(char *restrict s, ssize_t size,
+    const char *restrict fmt, ...);
+// vstprintf - va_list string truncate print formatted
 format_attr(printf, 3, 0)
-inline int vsnprintf_(char *restrict s, ssize_t size, const char *restrict fmt,
-    va_list ap);
+inline int vsnprintf_(char *restrict s, ssize_t size,
+    const char *restrict fmt, va_list ap);
 
 
 inline int
diff --git a/lib/string/sprintf/stpeprintf.h b/lib/string/sprintf/stpeprintf.h
index 19987caaa..dc422bade 100644
--- a/lib/string/sprintf/stpeprintf.h
+++ b/lib/string/sprintf/stpeprintf.h
@@ -16,61 +16,16 @@
 
 
 #if !defined(HAVE_STPEPRINTF)
+// stpeprintf - string offset-pointer end-pointer print formatted
 format_attr(printf, 3, 4)
 inline char *stpeprintf(char *dst, char *end, const char *restrict fmt, ...);
+// vstpeprintf - va_list string offset-pointer end-pointer print formatted
 format_attr(printf, 3, 0)
 inline char *vstpeprintf(char *dst, char *end, const char *restrict fmt,
     va_list ap);
 #endif
 
 
-/*
- * SYNOPSIS
- *	[[gnu::format(printf, 3, 4)]]
- *	char *_Nullable stpeprintf(char *_Nullable dst, char end[0],
- *	                           const char *restrict fmt, ...);
- *
- *	[[gnu::format(printf, 3, 0)]]
- *	char *_Nullable vstpeprintf(char *_Nullable dst, char end[0],
- *	                           const char *restrict fmt, va_list ap);
- *
- *
- * ARGUMENTS
- *	dst	Destination buffer where to write a string.
- *
- *	end	Pointer to one after the last element of the buffer
- *		pointed to by `dst`.  Usually, it should be calculated
- *		as `dst + countof(dst)`.
- *
- *	fmt	Format string
- *
- *	...
- *	ap	Variadic argument list
- *
- * DESCRIPTION
- *	These functions are very similar to [v]snprintf(3).
- *
- *	The destination buffer is limited by a pointer to its end --one
- *	after its last element-- instead of a size.  This allows
- *	chaining calls to it safely, unlike [v]snprintf(3), which is
- *	difficult to chain without invoking Undefined Behavior.
- *
- * RETURN VALUE
- *	dst + strlen(dst)
- *		On success, these functions return a pointer to the
- *		terminating NUL byte.
- *
- *	NULL	On error.
- *
- * ERRORS
- *	E2BIG	The string was truncated.
- *
- *	These functions may fail for the same reasons as vsnprintf(3).
- *
- *	If dst is NULL at input, this function doesn't clobber errno.
- */
-
-
 #if !defined(HAVE_STPEPRINTF)
 inline char *
 stpeprintf(char *dst, char *end, const char *restrict fmt, ...)
diff --git a/lib/string/strcpy/stpecpy.h b/lib/string/strcpy/stpecpy.h
index 6719bb2a1..d564d778b 100644
--- a/lib/string/strcpy/stpecpy.h
+++ b/lib/string/strcpy/stpecpy.h
@@ -17,49 +17,12 @@
 
 
 #if !defined(HAVE_STPECPY)
+// stpecpy - string offset-pointer end-pointer copy
 ATTR_STRING(3)
 inline char *stpecpy(char *dst, char *end, const char *restrict src);
 #endif
 
 
-/*
- * SYNOPSIS
- *	[[gnu::null_terminated_string_arg(3)]]
- *	char *_Nullable stpecpy(char *_Nullable dst, char end[0],
- *	                        const char *restrict src);
- *
- * ARGUMENTS
- *	dst	Destination buffer where to copy a string.
- *
- *	end	Pointer to one after the last element of the buffer
- *		pointed to by `dst`.  Usually, it should be calculated
- *		as `dst + countof(dst)`.
- *
- *	src	Source string to be copied into dst.
- *
- * DESCRIPTION
- *	This function copies the string pointed to by src, into a string
- *	at the buffer pointed to by dst.  If the destination buffer,
- *	limited by a pointer to its end --one after its last element--,
- *	isn't large enough to hold the copy, the resulting string is
- *	truncated.
- *
- *	This function can be chained with calls to [v]stpeprintf().
- *
- * RETURN VALUE
- *	dst + strlen(dst)
- *		On success, this function returns a pointer to the
- *		terminating NUL byte.
- *
- *	NULL	On error.
- *
- * ERRORS
- *	E2BIG	The string was truncated.
- *
- *	If dst is NULL at input, this function doesn't clobber errno.
- */
-
-
 #if !defined(HAVE_STPECPY)
 inline char *
 stpecpy(char *dst, char *end, const char *restrict src)