... which is why we documented it in Documentation/networking/phy.rst,
but it seems folk who run into RGMII stuff don't read that document.

I'm wondering if we can come up with some kernel-doc compatible way to
document them in linux/phy.h instead, which may stand an improved
chance of being read?

Move the relevant text from Documentation/networking/phy.rst into
linux/phy.h as a linux doc format comment. 

"include" that header file into Documentation/networking/phy.rst
with

.. kernel-doc:: include/linux/phy.h

-Tony