fts: Document thread (un)safety

MFC after: 3 days
Sponsored by: Klara, Inc.
Reviewed by: markj
Differential Revision: https://reviews.freebsd.org/D52828

(cherry picked from commit 64f8416afd4cd042b34e3e975f84fb3493397828)

fts: Further improve the manual page

• Add subsections for the three functions that didn't already have one.
• Add a RETURN VALUES section.
• Improve the grammar somewhat.
• Clarify that fts_read() will not set errno to 0 if called again after having already returned NULL.

Sponsored by: Klara, Inc.
Reviewed by: bcr, markj
Differential Revision: https://reviews.freebsd.org/D52925

(cherry picked from commit a802334d86c7173ddd7776a20065bd5682f25f67)