Updated documentation

Author: kb2ma

examples/gcoap/README.md

@@ -1,6 +1,6 @@
 # gcoap Example
 
-This application provides command line access to gcoap, a GNRC implementation of CoAP. See the [CoAP spec][1] for background, and the Modules>Networking>GNRC>CoAP topic in the source documentation for the structure of the implementation.
+This application provides command line access to gcoap, a high-level API for CoAP messaging. See the [CoAP spec][1] for background, and the Modules>Networking>GNRC>CoAP topic in the source documentation for the structure of the implementation.
 
 We support two setup options for this example:
 

sys/include/net/gcoap.h

@@ -9,14 +9,19 @@
 /**
  * @defgroup    net_gcoap  CoAP
  * @ingroup     net
- * @brief       sock-based implementation of CoAP protocol, RFC 7252
- *
- * ## Architecture ##
- * Requests and responses are exchanged via an asynchronous RIOT message
- * processing thread. Depends on nanocoap for base level structs and
- * functionality.
- *
- * Uses a single UDP port for communication to support RFC 6282 compression.
+ * @brief       High-level interface to CoAP messaging
+ *
+ * gcoap internalizes the event processing loop and provides a simple API for
+ * writing CoAP (RFC 7252) protocol data. Server operation requires a list of
+ * resource paths with callbacks for writing the response. Client operation uses
+ * a function to send a request, with a callback for reading the server
+ * response. Generation of request/response data requires from one to three
+ * well-defined steps, depending on inclusion of a payload.
+ * 
+ * Internally, requests and responses are exchanged via the sock application
+ * networking API from a RIOT message processing thread. Depends on the nanocoap
+ * package for base level structs and functionality. Uses a single UDP port for
+ * communication to support RFC 6282 compression.
  *
  * ## Server Operation ##
  *
@@ -61,11 +66,10 @@
  *
  * ## Client Operation ##
  *
- * gcoap uses RIOT's asynchronous messaging facility to send and receive
- * messages. So, client operation includes two phases:  creating and sending a
- * request, and handling the response aynchronously in a client supplied
- * callback.  See `examples/gcoap/gcoap_cli.c` for a simple example of sending
- * a request and reading the response.
+ * Client operation includes two phases:  creating and sending a request, and
+ * handling the response aynchronously in a client supplied callback.  See
+ * `examples/gcoap/gcoap_cli.c` for a simple example of sending a request and
+ * reading the response.
  *
  * ### Creating a request ###
  *
@@ -85,8 +89,8 @@
  * as described above. The gcoap_request() function is inline, and uses those
  * two functions.
  *
- * Finally, call gcoap_req_send() with the destination host and port, as well
- * as a callback function for the host's response.
+ * Finally, call gcoap_req_send2() for the destination endpoint, as well as a
+ * callback function for the host's response.
  *
  * ### Handling the response ###
  *
@@ -114,13 +118,13 @@
  * header and the payload. So, gcoap provides space in the buffer for them in
  * the request/response ...init() function, and then writes them during
  * gcoap_finish(). We trade some inefficiency/work in the buffer for
- * simplicity for the user.
+ * simplicity in the API.
  *
  * ### Waiting for a response ###
  *
- * We take advantage of RIOT's GNRC stack by using an xtimer to wait for a
- * response, so the gcoap thread does not block while waiting. The user is
- * notified via the same callback whether the message is received or the wait
+ * We take advantage of RIOT's asynchronous messaging by using an xtimer to wait
+ * for a response, so the gcoap thread does not block while waiting. The user is
+ * notified via the same callback, whether the message is received or the wait
  * times out. We track the response with an entry in the
  * `_coap_state.open_reqs` array.
  *