Clarify the actual purpose of ENET_PACKET_FLAG_SENT

[cher-nov]

It is currently not clear from the documentation that the sole purpose of ENET_PACKET_FLAG_SENT is to check for it in the designated packet->freeCallback function when releasing the packet. This is according directly to the next code:

enet/protocol.c

Lines 175 to 185 in a356ac0

	if (outgoingCommand -> packet != NULL)
	{
	-- outgoingCommand -> packet -> referenceCount;
	if (outgoingCommand -> packet -> referenceCount == 0)
	{
	outgoingCommand -> packet -> flags |= ENET_PACKET_FLAG_SENT;
	enet_packet_destroy (outgoingCommand -> packet);
	}
	}

enet/protocol.c

Lines 267 to 280 in a356ac0

	if (outgoingCommand -> packet != NULL)
	{
	if (wasSent)
	peer -> reliableDataInTransit -= outgoingCommand -> fragmentLength;
	-- outgoingCommand -> packet -> referenceCount;
	if (outgoingCommand -> packet -> referenceCount == 0)
	{
	outgoingCommand -> packet -> flags |= ENET_PACKET_FLAG_SENT;
	enet_packet_destroy (outgoingCommand -> packet);
	}
	}

enet/packet.c

Lines 53 to 68 in a356ac0

	/** Destroys the packet and deallocates its data.
	@param packet packet to be destroyed
	*/
	void
	enet_packet_destroy (ENetPacket * packet)
	{
	if (packet == NULL)
	return;
	if (packet -> freeCallback != NULL)
	(* packet -> freeCallback) (packet);
	if (! (packet -> flags & ENET_PACKET_FLAG_NO_ALLOCATE) &&
	packet -> data != NULL)
	enet_free (packet -> data);
	enet_free (packet);
	}

Also, the name of the constant itself is somewhat ambiguous, since the documentation does not indicate whether it is set only upon a complete transfer of the packet (i.e. acknowledged delivery) or after any partial / failed / etc attempts.

The ability for the sender to check this flag on the packet is very useful, for example, in the case of transferring large files so as not to store them entirely in memory and not send explicit delivery confirmations in addition to the already existing library ones (and therefore redundant).