git: 36de8bb22667 - main - kassert.h: update MPASS definition commentary

The branch main has been updated by mhorne:

URL: https://cgit.FreeBSD.org/src/commit/?id=36de8bb226671ef9fe373d8d95f77cdb76157738

commit 36de8bb226671ef9fe373d8d95f77cdb76157738
Author:     Mitchell Horne <mhorne@FreeBSD.org>
AuthorDate: 2024-03-21 15:21:41 +0000
Commit:     Mitchell Horne <mhorne@FreeBSD.org>
CommitDate: 2024-03-21 15:24:47 +0000

    kassert.h: update MPASS definition commentary
    
    We now have a detailed man page describing both MPASS and KASSERT. Give
    a warning that careless use of MPASS can result in inadequate assertion
    messages, and point to the MPASS(9) page which describes this.
    
    While here add a comment above the KASSERT definitions pointing to the
    man page.
    
    Suggested by:   bz
    Reviewed by:    emaste
    MFC after:      1 week
    Sponsored by:   The FreeBSD Foundation
    Differential Revision:  https://reviews.freebsd.org/D44438
---
 sys/sys/kassert.h | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/sys/sys/kassert.h b/sys/sys/kassert.h
index 25e2b025a11a..ab2313bcbd8b 100644
--- a/sys/sys/kassert.h
+++ b/sys/sys/kassert.h
@@ -142,6 +142,9 @@ void	kassert_panic(const char *fmt, ...)  __printflike(1, 2);
 #  endif /* defined(WITNESS) || defined(INVARIANT_SUPPORT) */
 #endif /* _STANDALONE */
 
+/*
+ * Kernel assertion; see KASSERT(9) for details.
+ */
 #if (defined(_KERNEL) && defined(INVARIANTS)) || defined(_STANDALONE)
 #define	KASSERT(exp,msg) do {						\
 	if (__predict_false(!(exp)))					\
@@ -154,8 +157,11 @@ void	kassert_panic(const char *fmt, ...)  __printflike(1, 2);
 
 #ifdef _KERNEL
 /*
- * Helpful macros for quickly coming up with assertions with informative
- * panic messages.
+ * Macros for generating panic messages based on the exact condition text.
+ *
+ * NOTE: Use these with care, as the resulting message might omit key
+ * information required to understand the assertion failure. Consult the
+ * MPASS(9) man page for guidance.
  */
 #define MPASS(ex)		MPASS4(ex, #ex, __FILE__, __LINE__)
 #define MPASS2(ex, what)	MPASS4(ex, what, __FILE__, __LINE__)