Unclear or wrong documentation in nxd_mqtt_client.c:_nxd_mqtt_release_receive_packet()

[jespertragardh]

Describe the bug
nxd_mqtt_client.c:_nxd_mqtt_release_receive_packet()

The documentation says:

/*  FUNCTION                                               RELEASE        */
/*                                                                        */
/*    _nxd_mqtt_release_receive_packet                    PORTABLE C      */
/*                                                           6.4.3        */
/*  AUTHOR                                                                */
/*                                                                        */
/*    Yuxin Zhou, Microsoft Corporation                                   */
/*                                                                        */
/*  DESCRIPTION                                                           */
/*                                                                        */
/*    This internal function releases a receive packet.                   */
/*    A receive packet is allocated to store QoS 1 and 2 messages.        */
/*    Upon a message being properly acknowledged, the packet can          */
/*    be released.                                                        */
/*
…
/**************************************************************************/
static VOID _nxd_mqtt_release_receive_packet(NXD_MQTT_CLIENT *client_ptr, NX_PACKET *packet_ptr, NX_PACKET *previous_packet_ptr)

I don't think that is correct.

The only thing added to client_ptr -> message_receive_queue_head, which this function works with, are complete MQTT PUBLISH messages from the broker (see _nxd_mqtt_process_publish(…)).
From what I can see, received messages are not stored until they are acknowledged. The PUBACK/PUBREC messages are put in the transmit queue (with checking for duplicates) and client_ptr -> message_receive_queue_head is dequeued in _nxd_mqtt_client_message_get(…).

It seems that the documentation has been copy-pasted from _nxd_mqtt_release_transmit_packet() and minimally adapted.

https://github.com/eclipse-threadx/netxduo/blob/8b6e03ac30ab688bec02c69d42f2304b7f72a202/addons/mqtt/nxd_mqtt_client.c

Impact
Confused developers who look for the code to allocate the receive packets for QoS 1/2 messages but cannot find it.

[jespertragardh]

As a side note, the parameter previous_packet_ptr is redundant. This static function is always called with previous_packet_ptr == NX_NULL.

This differs from _nxd_mqtt_release_transmit_packet(…) where this parameter is used.

So previous_packet_ptr could be removed to reduce complexity.