getopt_long(3): Document behavior of leading characters in optstring

Leading '+', '-', and ':' in optstring have special meaning. We briefly
mention that the first two have special meaning in that we say
POSIXLY_CORRECT turns them off, but we don't actually document their
meaning. Add a paragraph to RETURN VALUES explaining how they control
the treatment of non-option arguments.

A leading ':' has no mention; add a note that it suppresses warnings about
missing arguments.

Reviewed by: jilles
MFC after: 1 week
Differential Revision: https://reviews.freebsd.org/D14142