Allow ships to arrive from hangars on player ships

[The-E]

A longstanding issue for capship command missions has been that hangars on player ships don't work. The reason for this was that the engine kept the player ship in the Arrival_List; according to the :V: comments, this was done to allow respawns in multiplayer.
I've amended the check so that the player ship gets treated correctly in singleplayer.

[Goober5000]

The new change ought to have comments. Add one to the function header that explains why returning NULL is the right thing to do (for any and all functions that might call it), and add another comment to the if() block that explains how the conditions work.

[The-E]

Added the requested comments.

[Goober5000]

Looks good!

I was about to approve the merge, and then it occurred to me that we should test that respawns still work in multiplayer. Could you test that, or alternatively could you trace through the code logic to make sure that respawns don't depend on this function returning the old result?

[The-E]

Yeah, I should see if I can get some testing done on this. That said, this is why I put the call to ship_name_lookup in there; As I understand it, that function should return -1 if the ship being looked up is not currently present in-game (which should be the case for players waiting for respawn).

[Echelon9]

Given touching this function and mission_parse_get_arrival_ship(), would suggest you provide the function documentation with Doxygen features. e.g. https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html

[The-E]

Added comment tweaks.
In addition, a look through the player death code shows that player objects get changed to the OBJ_GHOST type on death, this will cause ship_name_lookup to return -1 if the player is currently awaiting respawn, which will make this work just as it did before.

[MageKing17]

Nothing else jumps out at me.

[asarium]

I noticed you use \brief instead of @brief and also kept that style for the rest of the comments. Any specific reason you did that? The rest of the code uses the @ variant of the doxygen comments.

[The-E]

I was looking at the comments in the hud code for guidance. Easy enough to fix.

[MageKing17]

Does this affect any retail missions?

[The-E]

Good point. I'll revert the change and change the comment instead

[The-E]

I think the use of WF_NEVER_EXISTED should be audited to see if its name matches its function, as I have a sneaking suspicion that it doesn't.

[Goober5000]

WF_NEVER_EXISTED does match its function, but it is only checked in one place -- the sexp_query_has_yet_to_arrive helper function -- in a way that appears redundant.

Actually, this situation is rather complicated and carries some interesting consequences. See #379.