diff --git a/include/mimalloc/internal.h b/include/mimalloc/internal.h
index 51d8aa1e..791eeb99 100644
--- a/include/mimalloc/internal.h
+++ b/include/mimalloc/internal.h
@@ -8,6 +8,12 @@ terms of the MIT license. A copy of the license can be found in the file
 #ifndef MIMALLOC_INTERNAL_H
 #define MIMALLOC_INTERNAL_H
 
+
+// --------------------------------------------------------------------------
+// This file contains the interal API's of mimalloc and various utility
+// functions and macros.
+// --------------------------------------------------------------------------
+
 #include "mimalloc/types.h"
 #include "mimalloc/track.h"
 
diff --git a/include/mimalloc/prim.h b/include/mimalloc/prim.h
index 1a4fb5d8..97d8b45d 100644
--- a/include/mimalloc/prim.h
+++ b/include/mimalloc/prim.h
@@ -8,10 +8,17 @@ terms of the MIT license. A copy of the license can be found in the file
 #ifndef MIMALLOC_PRIM_H
 #define MIMALLOC_PRIM_H
 
+
+// --------------------------------------------------------------------------
+// This file specifies the primitive portability API.
+// Each OS/host needs to implement these primitives, see `src/prim`
+// for implementations on Window, macOS, WASI, and Linux/Unix.
+//
 // note: on all primitive functions, we always get:
 //  addr != NULL and page aligned
 //  size > 0     and page aligned
 //  return value is an error code an int where 0 is success.
+// --------------------------------------------------------------------------
 
 // OS memory configuration
 typedef struct mi_os_mem_config_s {
diff --git a/include/mimalloc/types.h b/include/mimalloc/types.h
index da4b423f..90b7b3e4 100644
--- a/include/mimalloc/types.h
+++ b/include/mimalloc/types.h
@@ -8,6 +8,17 @@ terms of the MIT license. A copy of the license can be found in the file
 #ifndef MIMALLOC_TYPES_H
 #define MIMALLOC_TYPES_H
 
+// --------------------------------------------------------------------------
+// This file contains the main type definitions for mimalloc:
+// mi_heap_t      : all data for a thread-local heap, contains
+//                  lists of all managed heap pages.
+// mi_segment_t   : a larger chunk of memory (32GiB) from where pages
+//                  are allocated.
+// mi_page_t      : a mimalloc page (usually 64KiB or 512KiB) from
+//                  where objects are allocated.
+// --------------------------------------------------------------------------
+
+
 #include <stddef.h>   // ptrdiff_t
 #include <stdint.h>   // uintptr_t, uint16_t, etc
 #include "mimalloc/atomic.h"  // _Atomic