- * Assembles a new packet to be ready for send out. The buffer sent as
- * argument must include the data to be sent and it must not be encrypted.
- * The packet also must have enough free space so that the SILC header
- * and padding maybe added to the packet. The packet is encrypted after
- * this function has returned.
- *
- * The buffer sent as argument should be something like following:
- *
- * --------------------------------------------
- * | head | data | tail |
- * --------------------------------------------
- * ^ ^
- * 58 bytes x bytes
- *
- * So that the SILC header and 1 - 16 bytes of padding can fit to
- * the buffer. After assembly the buffer might look like this:
- *
- * --------------------------------------------
- * | data | |
- * --------------------------------------------
- * ^ ^
- * Start of assembled packet
- *
- * Packet construct is as follows (* = won't be encrypted):
- *
- * n bytes SILC Header
- * 2 bytes Payload length (*)
- * 1 byte Flags
- * 1 byte Packet type
- * 2 bytes Source ID Length
- * 2 bytes Destination ID Length
- * 1 byte Source ID Type
- * n bytes Source ID
- * 1 byte Destination ID Type
- * n bytes Destination ID
- *
- * 1 - 16 bytes Padding
- *
- * n bytes Data payload
- *
- * All fields in the packet will be authenticated by MAC. The MAC is
- * not computed here, it must be computed separately before encrypting
- * the packet.
+ * Assembles new packet to be ready for encrypting and sending out.
+ * The `packet' is filled by caller to include the packet header specific
+ * values. This prepares the socket connection's `sock' outoing buffer
+ * for sending data, and returns the assembled packet to the
+ * `assembled_packet' pointer sent by the caller. The `assembled_packet'
+ * is a reference to the socket connection's outgoing buffer. The
+ * returned packet can be encrypted, and then sent to network by calling
+ * silc_packet_send function. The `assembled_packet' may be freely
+ * modified (like encrypted etc.) but it must not be freed, since it is
+ * reference from `sock' outgoing buffer, and it is const.