From ac3562952097e616aab711bc614fbe78ac8fd58d Mon Sep 17 00:00:00 2001
From: Peter Mitsis <peter.mitsis@intel.com>
Date: Wed, 28 May 2025 16:34:00 -0700
Subject: [PATCH] doc: arch: Update file summary for kernel interfaces

Updates the file summary on the various arch-specific kernel
interfaces to accomplish two things:
  1. Fix the path in the comment
  2. Standardize on language/format.

Signed-off-by: Peter Mitsis <peter.mitsis@intel.com>
---
 include/zephyr/arch/arc/arch.h         | 2 +-
 include/zephyr/arch/arm/arch.h         | 2 +-
 include/zephyr/arch/arm64/arch.h       | 2 +-
 include/zephyr/arch/mips/arch.h        | 9 +++++++++
 include/zephyr/arch/posix/arch.h       | 6 +++---
 include/zephyr/arch/riscv/arch.h       | 4 +++-
 include/zephyr/arch/rx/arch.h          | 9 +++++++++
 include/zephyr/arch/sparc/arch.h       | 4 +++-
 include/zephyr/arch/x86/arch.h         | 9 +++++++++
 include/zephyr/arch/x86/ia32/arch.h    | 5 +++--
 include/zephyr/arch/x86/intel64/arch.h | 8 ++++++++
 include/zephyr/arch/xtensa/arch.h      | 6 ++++--
 12 files changed, 54 insertions(+), 12 deletions(-)

diff --git a/include/zephyr/arch/arc/arch.h b/include/zephyr/arch/arc/arch.h
index b3751c6041ce..2679b76a915f 100644
--- a/include/zephyr/arch/arc/arch.h
+++ b/include/zephyr/arch/arc/arch.h
@@ -10,7 +10,7 @@
  *
  * This header contains the ARC specific kernel interface.  It is
  * included by the kernel interface architecture-abstraction header
- * include/arch/cpu.h)
+ * (include/zephyr/arch/cpu.h).
  */
 
 #ifndef ZEPHYR_INCLUDE_ARCH_ARC_ARCH_H_
diff --git a/include/zephyr/arch/arm/arch.h b/include/zephyr/arch/arm/arch.h
index 7bf385a0219f..a870c6f0f63d 100644
--- a/include/zephyr/arch/arm/arch.h
+++ b/include/zephyr/arch/arm/arch.h
@@ -10,7 +10,7 @@
  *
  * This header contains the ARM AArch32 specific kernel interface.  It is
  * included by the kernel interface architecture-abstraction header
- * (include/arm/cpu.h)
+ * (include/zephyr/arch/cpu.h).
  */
 
 #ifndef ZEPHYR_INCLUDE_ARCH_ARM_ARCH_H_
diff --git a/include/zephyr/arch/arm64/arch.h b/include/zephyr/arch/arm64/arch.h
index 1f38bd84a2f0..30ad05300a96 100644
--- a/include/zephyr/arch/arm64/arch.h
+++ b/include/zephyr/arch/arm64/arch.h
@@ -10,7 +10,7 @@
  *
  * This header contains the ARM64 specific kernel interface.  It is
  * included by the kernel interface architecture-abstraction header
- * (include/arm64/cpu.h)
+ * (include/zephyr/arch/cpu.h).
  */
 
 #ifndef ZEPHYR_INCLUDE_ARCH_ARM64_ARCH_H_
diff --git a/include/zephyr/arch/mips/arch.h b/include/zephyr/arch/mips/arch.h
index f99744bf0865..7fc4dd733dd5 100644
--- a/include/zephyr/arch/mips/arch.h
+++ b/include/zephyr/arch/mips/arch.h
@@ -6,6 +6,15 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @brief MIPS specific kernel interface header
+ *
+ * This header contains the MIPS specific kernel interface.  It is
+ * included by the kernel interface architecture-abstraction header
+ * (include/zephyr/arch/cpu.h).
+ */
+
 #ifndef ZEPHYR_INCLUDE_ARCH_MIPS_ARCH_H_
 #define ZEPHYR_INCLUDE_ARCH_MIPS_ARCH_H_
 
diff --git a/include/zephyr/arch/posix/arch.h b/include/zephyr/arch/posix/arch.h
index 7dbfb6b38645..105f847eb1e6 100644
--- a/include/zephyr/arch/posix/arch.h
+++ b/include/zephyr/arch/posix/arch.h
@@ -8,12 +8,12 @@
 /**
  * @file
  * @brief POSIX arch specific kernel interface header
- * This header contains the POSIX arch specific kernel interface.
- * It is included by the generic kernel interface header (include/arch/cpu.h)
  *
+ * This header contains the POSIX arch specific kernel interface. It is
+ * included by the kernel interface architecture-abstraction header
+ * (include/zephyr/arch/cpu.h).
  */
 
-
 #ifndef ZEPHYR_INCLUDE_ARCH_POSIX_ARCH_H_
 #define ZEPHYR_INCLUDE_ARCH_POSIX_ARCH_H_
 
diff --git a/include/zephyr/arch/riscv/arch.h b/include/zephyr/arch/riscv/arch.h
index 4cdedb700d32..6a05d3f8b630 100644
--- a/include/zephyr/arch/riscv/arch.h
+++ b/include/zephyr/arch/riscv/arch.h
@@ -8,8 +8,10 @@
 /**
  * @file
  * @brief RISCV specific kernel interface header
+ *
  * This header contains the RISCV specific kernel interface.  It is
- * included by the generic kernel interface header (arch/cpu.h)
+ * included by the kernel interface architecture-abstraction header
+ * (include/zephyr/arch/cpu.h).
  */
 
 #ifndef ZEPHYR_INCLUDE_ARCH_RISCV_ARCH_H_
diff --git a/include/zephyr/arch/rx/arch.h b/include/zephyr/arch/rx/arch.h
index db3bebc8ba02..c10171188b40 100644
--- a/include/zephyr/arch/rx/arch.h
+++ b/include/zephyr/arch/rx/arch.h
@@ -4,6 +4,15 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @brief Renesas RX specific kernel interface header
+ *
+ * This header contains the Renesas RX specific kernel interface.  It is
+ * included by the kernel interface architecture-abstraction header
+ * (include/zephyr/arch/cpu.h).
+ */
+
 #ifndef ZEPHYR_INCLUDE_ARCH_RX_ARCH_H_
 #define ZEPHYR_INCLUDE_ARCH_RX_ARCH_H_
 
diff --git a/include/zephyr/arch/sparc/arch.h b/include/zephyr/arch/sparc/arch.h
index c1d87682f39b..f463ddb464f5 100644
--- a/include/zephyr/arch/sparc/arch.h
+++ b/include/zephyr/arch/sparc/arch.h
@@ -7,8 +7,10 @@
 /**
  * @file
  * @brief SPARC specific kernel interface header
+ *
  * This header contains the SPARC specific kernel interface.  It is
- * included by the generic kernel interface header (arch/cpu.h)
+ * included by the kernel interface architecture-abstraction header
+ * (include/zephyr/arch/cpu.h).
  */
 
 #ifndef ZEPHYR_INCLUDE_ARCH_SPARC_ARCH_H_
diff --git a/include/zephyr/arch/x86/arch.h b/include/zephyr/arch/x86/arch.h
index 90d2fa0c51a1..adb8d06fa6cc 100644
--- a/include/zephyr/arch/x86/arch.h
+++ b/include/zephyr/arch/x86/arch.h
@@ -3,6 +3,15 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @brief X86 specific kernel interface header
+ *
+ * This header contains the X86 specific kernel interfaces for both
+ * IA-32 and Intel-64.  It is included by the kernel interface
+ * architecture-abstraction header (include/zephyr/arch/cpu.h).
+ */
+
 #ifndef ZEPHYR_INCLUDE_ARCH_X86_ARCH_H_
 #define ZEPHYR_INCLUDE_ARCH_X86_ARCH_H_
 
diff --git a/include/zephyr/arch/x86/ia32/arch.h b/include/zephyr/arch/x86/ia32/arch.h
index b82e0db0f173..6b90fd2737ab 100644
--- a/include/zephyr/arch/x86/ia32/arch.h
+++ b/include/zephyr/arch/x86/ia32/arch.h
@@ -7,8 +7,9 @@
 /**
  * @file
  * @brief IA-32 specific kernel interface header
- * This header contains the IA-32 specific kernel interface.  It is included
- * by the generic kernel interface header (include/arch/cpu.h)
+ *
+ * This header contains the IA-32 portion of the X86 specific kernel
+ * interface (see include/zephyr/arch/x86/cpu.h).
  */
 
 #ifndef ZEPHYR_INCLUDE_ARCH_X86_IA32_ARCH_H_
diff --git a/include/zephyr/arch/x86/intel64/arch.h b/include/zephyr/arch/x86/intel64/arch.h
index 86de01297f47..0376d4a90fd9 100644
--- a/include/zephyr/arch/x86/intel64/arch.h
+++ b/include/zephyr/arch/x86/intel64/arch.h
@@ -3,6 +3,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * @file
+ * @brief Intel-64 specific kernel interface header
+ *
+ * This header contains the Intel-64 portion of the X86 specific kernel
+ * interface (see include/zephyr/arch/x86/cpu.h).
+ */
+
 #ifndef ZEPHYR_INCLUDE_ARCH_X86_INTEL64_ARCH_H_
 #define ZEPHYR_INCLUDE_ARCH_X86_INTEL64_ARCH_H_
 
diff --git a/include/zephyr/arch/xtensa/arch.h b/include/zephyr/arch/xtensa/arch.h
index 6255249f8e7d..4abfbeeb4350 100644
--- a/include/zephyr/arch/xtensa/arch.h
+++ b/include/zephyr/arch/xtensa/arch.h
@@ -6,8 +6,10 @@
 /**
  * @file
  * @brief Xtensa specific kernel interface header
- * This header contains the Xtensa specific kernel interface.  It is included
- * by the generic kernel interface header (include/zephyr/arch/cpu.h)
+ *
+ * This header contains the Xtensa specific kernel interface.  It is
+ * included by the kernel interface architecture-abstraction header
+ * (include/zephyr/arch/cpu.h).
  */
 
 #ifndef ZEPHYR_INCLUDE_ARCH_XTENSA_ARCH_H_