I long ago gave up on adhering exactly to the official API in my cores out of frustration with things like this. I used to just say "Well that's what the official core does" - but the official behavior is ill-defined and occasionally just bad enough that I gave up -
What made me rip the enums out of megaTinyCore in fury was actually a long confusing debug process before discovering that I had accidentally capitalized the P in a pinMode call and wasn't getting a compile error. At which point I discovered that the code I'd taken from the official "megaavr" core used enums in that way and was horrified that I hadn't noticed for so long), The main advantage that the enums offered WAS that they wouldn't let you write things that weren't valid values to the pins, which was defeated by the compatibility code.
Aside from not using the enums on modern AVRs ("megaavr" is a totally wrong name, as Microchip uses "megaAVR" to mean something else) I try to maximize compatibility of the digitalRead()/etc functions even though I rarely use them because they are so mindbogglingly slow, bulky and awful.
I should probably revise the documentation of my cores to be more explicit about documenting return types and accepted input values for Arduino API functions as implemented in my cores, since yeah, they are not well defined in the official API documentation, and my cores do differ from the official implementation in a few subtle ways that are still consistent with the official documentation).
My general impression has been of the Arduino team being very good at outreach and making an IDE that doesn't have a tough learning curve and is generally good enough (I still don't us alternative IDEs, I know many people use VSCode or PIO with Arduino cores and libraries) particularly for educational applications) - who would have imagined that EMBEDDED C++ would be a effective language for students' first exposure to programming? But it seems to work better than a lot of introductory programming curriculums that use "easier" languages! But that they're not the best api designers. embedded developers. or hardware designers.