diff --git a/tool/_testc/python-3.14.8/pymacro.go b/tool/_testc/python-3.14.8/pymacro.go
index 86649218a..62db659ca 100644
--- a/tool/_testc/python-3.14.8/pymacro.go
+++ b/tool/_testc/python-3.14.8/pymacro.go
@@ -7,6 +7,8 @@ import (
 	_ "unsafe"
 )
 
+// Version helpers. These are primarily macros, but have exported equivalents.
+//
 //go:linkname Py_PACK_FULL_VERSION C.Py_PACK_FULL_VERSION
 func Py_PACK_FULL_VERSION(x c.Int, y c.Int, z c.Int, level c.Int, serial c.Int) c.Uint32T
 
diff --git a/tool/_testc/python-3.14.8/pyport.go b/tool/_testc/python-3.14.8/pyport.go
index e0753aaf1..d4ab1fb3e 100644
--- a/tool/_testc/python-3.14.8/pyport.go
+++ b/tool/_testc/python-3.14.8/pyport.go
@@ -13,9 +13,15 @@ const PY_BIG_ENDIAN = 0
 const PY_LITTLE_ENDIAN = 1
 const Py_CAN_START_THREADS = 1
 
+// uintptr_t is the C9X name for an unsigned integral type such that a
+// legitimate void* can be cast to uintptr_t and then back to void* again
+// without loss of information.  Similarly for intptr_t, wrt a signed
+// integral type.
 type PyUintptrT = c.UintptrT
 type PyIntptrT = c.IntptrT
 type PySsizeT = c.SsizeT
 type PyHashT = PySsizeT
 type PyUhashT = c.SizeT
+
+// Now PY_SSIZE_T_CLEAN is mandatory. This is just for backward compatibility.
 type PySsizeCleanT = PySsizeT
diff --git a/tool/_testc/python-3.14.8/pythread.go b/tool/_testc/python-3.14.8/pythread.go
index 226402bd6..f3a76117b 100644
--- a/tool/_testc/python-3.14.8/pythread.go
+++ b/tool/_testc/python-3.14.8/pythread.go
@@ -8,6 +8,8 @@ import (
 	_ "unsafe"
 )
 
+// Return status codes for Python lock acquisition.  Chosen for maximum
+// backwards compatibility, ie failure -> 0, success -> 1.
 type PyLockStatus c.Uint
 
 const (
@@ -17,11 +19,22 @@ const (
 )
 
 type PyThreadTypeLock uintptr
+
+// When Py_LIMITED_API is not defined, the type layout of Py_tss_t is
+// exposed to allow static allocation in the API clients.  Even in this case,
+// you must handle TSS keys through API functions due to compatibility.
 type X_PyTssT struct {
 	X_isInitialized c.Int
 	X_key           pthread.Key
 }
 type PyTssT = X_PyTssT
 
+// PY_TIMEOUT_MAX is the highest usable value (in microseconds) of PY_TIMEOUT_T
+// type, and depends on the system threading API.
+//
+// NOTE: this isn't the same value as `_thread.TIMEOUT_MAX`. The _thread module
+// exposes a higher-level API, with timeouts expressed in seconds and
+// floating-point numbers allowed.
+//
 //go:linkname PY_TIMEOUT_MAX C.PY_TIMEOUT_MAX
 var PY_TIMEOUT_MAX c.LongLong
diff --git a/tool/gen.go b/tool/gen.go
index fb5b7362b..f0de094f9 100644
--- a/tool/gen.go
+++ b/tool/gen.go
@@ -351,6 +351,7 @@ func ParseFlags(includeDirs []string, lang string) []string {
 // to those files.
 func ParseSources(index clang.Index, headerFiles, includeDirs []string, lang string) ([]cl.Source, error) {
 	flags := ParseFlags(includeDirs, lang)
+	flags = append(flags, "-fparse-all-comments")
 	files := make([]cl.Source, len(headerFiles))
 	for i, headerFile := range headerFiles {
 		tu, e := index.ParseTranslationUnit(clang.DetailedPreprocessingRecord, headerFile, flags...)