Clarify documentation around test target setting.

There was some confusion about the wording in this section regarding what happens with an example's `main` function. This tries to be more explicit to clarify what happens when an example is marked as a test.

This also adds a few other clarifications and a link to the reference documentation.

Closes #11528