Description
When using the Ethernet library with DHCP, Ethernet.maintain() should regularly be called to renew the loop when needed. However, the current documentation doesn't entirely make clear when or how often this should happen (the current docs could be implying that calling maintain() always tries to refresh the DHCP lease, but it first checks if the current lease time is still valid). Also, the Ethernet.begin() docs do not mention this at all.
I would propose to add this to the Ethernet.maintain() page as a second paragraph under "description":
You can call this function as often as you want, it will only re-request a DHCP lease when needed (returning 0 in all other cases). The easiest way is to just call it on every
loop()invocation, but less often is also fine. Not calling this function (or calling it significantly less then once per second) will prevent the lease to be renewed when the DHCP protocol requires this, continuing to use the expired lease instead (which will not directly break connectivity, but if the DHCP server leases the same address to someone else, things will likely break).
Additionally, I would propose adding this to the last paragraph of the description of Ethernet.begin():
To make sure the DHCP lease is properly renewed when needed, be sure to call
Ethernet.maintain()regularly.
Perhaps a second example would be helpful here?
The examples included with the library also don't use Ethernet.maintain(). From a quick grep at least Webserver, UdpNtpClient and DhcpChatServer would need to have a call added to their loop(). For bonus points, DhcpAddressPrinter should be modified to call Ethernet.maintain() and print a message and the new lease's details when the lease is renewed.