ASYNC_start_job: more readable documentation for handling ASYNC* APIs

[tomato42]

Recently I was trying to figure out how to use the OpenSSL APIs combined with the ASYNC multithreading and found the documentation hard to follow.

Added few more comments that would probably made it easier to the past me.

Checklist

• documentation is added or updated

[tomato42]

About the failing CI check:

doc/man3/ASYNC_start_job.pod:1: Missing man section number (likely, 3) in L<select(2)>
doc/man3/ASYNC_start_job.pod:1: Missing man section number (likely, 3) in L<poll(2)>
doc/man3/ASYNC_start_job.pod:1: reference to non-existing select(2)
doc/man3/ASYNC_start_job.pod:1: reference to non-existing poll(2)

we can't link to basic C man pages?

[nhorman]

According to this:
https://perldoc.perl.org/perlpod#Formatting-Codes

We should be able to. I wonder if successful linking is incumbent on the target man pages being installed? I would imagine that the ci images that do the doc-nits check have them all stripped

[nhorman]

Oh, I found the problem, its twofold:

1. find-doc-nits only checks for man pages in sections 1,3,5 and 7. We need to add section 2 to the check
2. find-doc-nits assumes all links resolve to files in the openssl repo (excluding hyperlinks and such). since unix man pages don't we would need to find some way to make them appear in the tree, have find-doc-nits understand them as nroff pages (rather than pod files), and not processes them

[tomato42]

Sounds like I shouldn't link to them then...

[nhorman]

yeah, probably not, as the L<> tag assumes that the link target is included in the docs tree. We could potentially use this syntax:

L<select|http://external.link.to/man/page/you/want/to/target

There are several sites that provide canonical man pages in html form, but I'm not sure what the policy is on linking to external sources

[tomato42]

no-shared-macos (macos-14) failure looks unrelated: seems to be a race condition in the test case

[beldmit]

LGTM

[openssl-machine]

This pull request is ready to merge

[nhorman]

merged, thank you for your contribution