In getopt(3) on both FreeBSD and macOS, it states (emphasis mine):
It is also possible to handle digits as option letters. This allows
getopt()to be used with programs that expect a number ("-3") as an option. This practice is wrong, and should not be used in any current development. It is provided for backward compatibility only.
But why is it wrong? Both man pages give some example code, but I don't get what they're trying to do. I don't see why using digits for command-line options need any special treatment.
Neither Linux' nor GNU's getopt(3) make any mention of digits as option letters nor that they're wrong. So why are digits as options allegedly wrong on FreeBSD and macOS?
I've seen programs in the wild, e.g., gzip, plus my own programs that use digits as options just fine.
But why is it wrong?
To the extent that it's wrong, that's because the author of the BSD manpage says it is. That may reflect a common opinion among BSD developers, but I'm having trouble finding anything more authoritative about it in the BSD documentation than what you're already looking at.
Note in particular that POSIX seems perfectly fine with digits as option names. Almost all it has to say about how option names should be chosen is:
Each option name should be a single alphanumeric character (the alnum character classification) from the portable character set.
That is inclusive of decimal digits, without any caveat.
Also, the POSIX documentation for getopt() does not contain anything analogous to the BSD remarks you ask about.
Both man pages give some example code, but I don't get what they're trying to do.
Note that it's really only one manpage. MacOS is a BSD derivative, and the Apple manpage you linked is just a re-skinning of the BSD page.
In any case, that example code appears to be trying to use getopt() to recognize program arguments consisting of a - character followed by possibly-many decimal digits as expressing a single number as one unified option. That's indeed nasty, and supporting it does run against POSIX guidelines, and I don't recommend it. But it also seems like a non sequitur to me.
I don't see why using digits for command-line options need any special treatment.
They don't, from a programming perspective, as long as they are to be treated as individual digits only. Nevertheless, that does leave open a potential to confuse users of your program when two or more decimal-digit options are ganged together. I take that to be what the BSD manpage is hot and bothered about, but going from there to single-digit options being wrong is too much of a jump for me.