net/goap: State and check that listeners are added individually

Add a an assertion on the added listener not having a trailing chain
instead of silently overwriting it, point out the precondition in the
documentation, and guide users who want to add more than one listener
towards a more efficient way.

sys/include/net/gcoap.h

@@ -690,6 +690,16 @@ kernel_pid_t gcoap_init(void);
 /**
  * @brief   Starts listening for resource paths
  *
+ * @pre @p listener is a valid pointer to a single listener (that is,
+ *      `listener->next == NULL`)
+ *
+ * @note If you are tempted to register a pre-linked chain of listeners,
+ *       consider placing all their resources in the resources array of a
+ *       single listener instead. In the few cases where this does not work
+ *       (that is, when the resources need a different `link_encoder` or other
+ *       fields of the listener struct), they can just be registered
+ *       individually.
+ *
  * @param[in] listener  Listener containing the resources.
  */
 void gcoap_register_listener(gcoap_listener_t *listener);

sys/net/application_layer/gcoap/gcoap.c

@@ -702,6 +702,10 @@ kernel_pid_t gcoap_init(void)
 
 void gcoap_register_listener(gcoap_listener_t *listener)
 {
+    /* That item will be overridden, ensure that the user expecting different
+     * behavior will notice this. */
+    assert(listener->next == NULL);
+
     if (!listener->link_encoder) {
         listener->link_encoder = gcoap_encode_link;
     }