Added a few more comments.

upb/decode.h

@@ -14,7 +14,6 @@ extern "C" {
 bool upb_decode(const char *buf, size_t size, upb_msg *msg,
                 const upb_msglayout *l, upb_arena *arena);
 
-
 #ifdef __cplusplus
 }  /* extern "C" */
 #endif

upb/decode.int.h

@@ -26,6 +26,14 @@ typedef struct upb_decstate {
 
 const char *fastdecode_dispatch(upb_decstate *d, const char *ptr, upb_msg *msg,
                                 const upb_msglayout *table, uint64_t hasbits);
+
+/* Error function that will abort decoding with longjmp(). We can't declare this
+ * UPB_NORETURN, even though it is appropriate, because if we do then compilers
+ * will "helpfully" refuse to tailcall to it
+ * (see: https://stackoverflow.com/a/55657013), which will defeat a major goal
+ * of our optimizations. That is also why we must declare it in a separate file,
+ * otherwise the compiler will see that it calls longjmp() and deduce that it is
+ * noreturn. */
 const char *fastdecode_err(upb_decstate *d);
 
 #include "upb/port_undef.inc"

upb/decode_fast.h

@@ -11,6 +11,8 @@
 
 struct upb_decstate;
 
+// The fallback, generic parsing function that can handle any field type.
+// This just uses the regular (non-fast) parser to parse a single field.
 const char *fastdecode_generic(struct upb_decstate *d, const char *ptr,
                                upb_msg *msg, const upb_msglayout *table,
                                uint64_t hasbits, uint64_t data);