improve documentation of examples

examples/dialect-custom/main.go

@@ -8,6 +8,11 @@ import (
 	"github.com/aler9/gomavlib/pkg/message"
 )
 
+// this example shows how to:
+// 1) create a custom dialect from a list of messages
+// 2) create a node which understands the custom dialect
+// 3) print incoming messages
+
 // this is a custom message.
 // It must be prefixed with "Message" and implement the message.Message interface.
 type MessageCustom struct {
@@ -21,15 +26,12 @@ func (*MessageCustom) GetID() uint32 {
 }
 
 func main() {
-	// create a custom dialect from messages
+	// create a custom dialect from a list of messages
 	dialect := &dialect.Dialect{3, []message.Message{
 		&MessageCustom{},
 	}}
 
-	// create a node which
-	// - communicates with a serial port
-	// - understands our custom dialect
-	// - writes messages with given system id
+	// create a node which understands the custom dialect
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointSerial{
@@ -46,7 +48,7 @@ func main() {
 	}
 	defer node.Close()
 
-	// print every message we receive
+	// print incoming messages
 	for evt := range node.Events() {
 		if frm, ok := evt.(*gomavlib.EventFrame); ok {
 			log.Printf("received: id=%d, %+v\n", frm.Message().GetID(), frm.Message())

examples/dialect-no/main.go

@@ -6,11 +6,12 @@ import (
 	"github.com/aler9/gomavlib"
 )
 
+// this example shows how to:
+// 1) create a node with no dialect, that doesn't attempt to decode messages
+// 2) print incoming messages
+
 func main() {
-	// create a node which
-	// - communicates with a serial port
-	// - does not use dialects
-	// - writes messages with given system id
+	// create a node with no dialect, that doesn't attempt to decode messages
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointSerial{
@@ -27,7 +28,7 @@ func main() {
 	}
 	defer node.Close()
 
-	// print every message we receive
+	// print incoming messages
 	for evt := range node.Events() {
 		if frm, ok := evt.(*gomavlib.EventFrame); ok {
 			log.Printf("received: id=%d, %+v\n", frm.Message().GetID(), frm.Message())

examples/endpoint-custom/main.go

@@ -8,6 +8,11 @@ import (
 	"github.com/aler9/gomavlib/pkg/dialects/ardupilotmega"
 )
 
+// this example shows how to:
+// 1) create a custom endpoint from a io.ReadWriteCloser
+// 2) create a node which communicates with the custom endpoint
+// 3) print incoming messages
+
 // this is an example struct that implements io.ReadWriteCloser.
 // it does not read anything and prints what it receives.
 // the only requirement is that Close() must release Read().
@@ -44,10 +49,7 @@ func main() {
 	// allocate the custom endpoint
 	endpoint := NewCustomEndpoint()
 
-	// create a node which
-	// - communicates with a custom endpoint
-	// - understands ardupilotmega dialect
-	// - writes messages with given system id
+	// create a node which communicates with the custom endpoint
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointCustom{endpoint},
@@ -64,7 +66,7 @@ func main() {
 	// queue a dummy message
 	endpoint.readChan <- []byte("\xfd\t\x01\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x01\x02\x03\x05\x03\xd9\xd1\x01\x02\x00\x00\x00\x00\x00\x0eG\x04\x0c\xef\x9b")
 
-	// print every message we receive
+	// print incoming messages
 	for evt := range node.Events() {
 		if frm, ok := evt.(*gomavlib.EventFrame); ok {
 			log.Printf("received: id=%d, %+v\n", frm.Message().GetID(), frm.Message())

examples/endpoint-serial/main.go

@@ -7,11 +7,12 @@ import (
 	"github.com/aler9/gomavlib/pkg/dialects/ardupilotmega"
 )
 
+// this example shows how to:
+// 1) create a node which communicates with a serial endpoint
+// 2) print incoming messages
+
 func main() {
-	// create a node which
-	// - communicates with a serial port
-	// - understands ardupilotmega dialect
-	// - writes messages with given system id
+	// create a node which communicates with a serial endpoint
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointSerial{
@@ -28,7 +29,7 @@ func main() {
 	}
 	defer node.Close()
 
-	// print every message we receive
+	// print incoming messages
 	for evt := range node.Events() {
 		if frm, ok := evt.(*gomavlib.EventFrame); ok {
 			log.Printf("received: id=%d, %+v\n", frm.Message().GetID(), frm.Message())

examples/endpoint-tcp-client/main.go

@@ -7,11 +7,12 @@ import (
 	"github.com/aler9/gomavlib/pkg/dialects/ardupilotmega"
 )
 
+// this example shows how to:
+// 1) create a node which communicates with a TCP endpoint in client mode
+// 2) print incoming messages
+
 func main() {
-	// create a node which
-	// - communicates with a TCP endpoint in client mode
-	// - understands ardupilotmega dialect
-	// - writes messages with given system id
+	// create a node which communicates with a TCP endpoint in client mode
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointTCPClient{"1.2.3.4:5600"},
@@ -25,7 +26,7 @@ func main() {
 	}
 	defer node.Close()
 
-	// print every message we receive
+	// print incoming messages
 	for evt := range node.Events() {
 		if frm, ok := evt.(*gomavlib.EventFrame); ok {
 			log.Printf("received: id=%d, %+v\n", frm.Message().GetID(), frm.Message())

examples/endpoint-tcp-server/main.go

@@ -7,11 +7,12 @@ import (
 	"github.com/aler9/gomavlib/pkg/dialects/ardupilotmega"
 )
 
+// this example shows how to:
+// 1) create a node which communicates with a TCP endpoint in server mode
+// 2) print incoming messages
+
 func main() {
-	// create a node which
-	// - communicates with a TCP endpoint in server mode
-	// - understands ardupilotmega dialect
-	// - writes messages with given system id
+	// create a node which communicates with a TCP endpoint in server mode
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointTCPServer{":5600"},
@@ -25,7 +26,7 @@ func main() {
 	}
 	defer node.Close()
 
-	// print every message we receive
+	// print incoming messages
 	for evt := range node.Events() {
 		if frm, ok := evt.(*gomavlib.EventFrame); ok {
 			log.Printf("received: id=%d, %+v\n", frm.Message().GetID(), frm.Message())

examples/endpoint-udp-broadcast/main.go

@@ -7,11 +7,12 @@ import (
 	"github.com/aler9/gomavlib/pkg/dialects/ardupilotmega"
 )
 
+// this example shows how to:
+// 1) create a node which communicates with a UDP endpoint in broadcast mode
+// 2) print incoming messages
+
 func main() {
-	// create a node which
-	// - communicates with an UDP endpoint in broadcast mode
-	// - understands ardupilotmega dialect
-	// - writes messages with given system id
+	// create a node which communicates with a UDP endpoint in broadcast mode
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointUDPBroadcast{BroadcastAddress: "192.168.7.255:5600"},
@@ -25,7 +26,7 @@ func main() {
 	}
 	defer node.Close()
 
-	// print every message we receive
+	// print incoming messages
 	for evt := range node.Events() {
 		if frm, ok := evt.(*gomavlib.EventFrame); ok {
 			log.Printf("received: id=%d, %+v\n", frm.Message().GetID(), frm.Message())

examples/endpoint-udp-client/main.go

@@ -7,11 +7,12 @@ import (
 	"github.com/aler9/gomavlib/pkg/dialects/ardupilotmega"
 )
 
+// this example shows how to:
+// 1) create a node which communicates with a UDP endpoint in client mode
+// 2) print incoming messages
+
 func main() {
-	// create a node which
-	// - communicates with an UDP endpoint in client mode
-	// - understands ardupilotmega dialect
-	// - writes messages with given system id
+	// create a node which communicates with a UDP endpoint in client mode
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointUDPClient{"1.2.3.4:5600"},
@@ -25,7 +26,7 @@ func main() {
 	}
 	defer node.Close()
 
-	// print every message we receive
+	// print incoming messages
 	for evt := range node.Events() {
 		if frm, ok := evt.(*gomavlib.EventFrame); ok {
 			log.Printf("received: id=%d, %+v\n", frm.Message().GetID(), frm.Message())

examples/endpoint-udp-server/main.go

@@ -7,11 +7,12 @@ import (
 	"github.com/aler9/gomavlib/pkg/dialects/ardupilotmega"
 )
 
+// this example shows how to:
+// 1) create a node which communicates with a UDP endpoint in server mode
+// 2) print incoming messages
+
 func main() {
-	// create a node which
-	// - communicates with an UDP endpoint in server mode.
-	// - understands ardupilotmega dialect
-	// - writes messages with given system id
+	// create a node which communicates with a UDP endpoint in server mode
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointUDPServer{":5600"},
@@ -25,7 +26,7 @@ func main() {
 	}
 	defer node.Close()
 
-	// print every message we receive
+	// print incoming messages
 	for evt := range node.Events() {
 		if frm, ok := evt.(*gomavlib.EventFrame); ok {
 			log.Printf("received: id=%d, %+v\n", frm.Message().GetID(), frm.Message())

examples/events/main.go

@@ -7,11 +7,12 @@ import (
 	"github.com/aler9/gomavlib/pkg/dialects/ardupilotmega"
 )
 
+// this example shows how to:
+// 1) create a node which communicates with a serial endpoint
+// 2) print incoming events
+
 func main() {
-	// create a node which
-	// - communicates with a serial port
-	// - understands ardupilotmega dialect
-	// - writes messages with given system id
+	// create a node which communicates with a serial endpoint
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointSerial{
@@ -28,7 +29,8 @@ func main() {
 	}
 	defer node.Close()
 
-	// gomavlib provides different kinds of event
+	// print incoming events.
+	// gomavlib provides different kinds of events.
 	for evt := range node.Events() {
 		switch ee := evt.(type) {
 		case *gomavlib.EventFrame:

examples/message-read/main.go

@@ -7,11 +7,12 @@ import (
 	"github.com/aler9/gomavlib/pkg/dialects/ardupilotmega"
 )
 
+// this example shows how to:
+// 1) create a node which communicates with a serial endpoint
+// 2) print selected incoming messages
+
 func main() {
-	// create a node which
-	// - communicates with a serial port
-	// - understands ardupilotmega dialect
-	// - writes messages with given system id
+	// create a node which communicates with a serial endpoint
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointSerial{
@@ -28,7 +29,7 @@ func main() {
 	}
 	defer node.Close()
 
-	// print selected messages
+	// print selected incoming messages
 	for evt := range node.Events() {
 		if frm, ok := evt.(*gomavlib.EventFrame); ok {
 			switch msg := frm.Message().(type) {

examples/message-write/main.go

@@ -7,11 +7,13 @@ import (
 	"github.com/aler9/gomavlib/pkg/dialects/ardupilotmega"
 )
 
+// this example shows how to:
+// 1) create a node which communicates with a serial endpoint
+// 2) wait for a specific incoming message
+// 3) write a reply message
+
 func main() {
-	// create a node which
-	// - communicates with a serial port
-	// - understands ardupilotmega dialect
-	// - writes messages with given system id
+	// create a node which communicates with a serial endpoint
 	node, err := gomavlib.NewNode(gomavlib.NodeConf{
 		Endpoints: []gomavlib.EndpointConf{
 			gomavlib.EndpointSerial{

examples/readwriter/main.go

@@ -13,6 +13,11 @@ import (
 // if NewNode() is not flexible enough, the library provides a low-level
 // frame reader and writer, that can be used with any kind of byte stream.
 
+// this example shows how to:
+// 1) allocate the low-level frame.ReadWriter around a io.ReadWriter
+// 2) read a frame, that contains a message
+// 3) write a message, that is automatically wrapped in a frame
+
 type readWriter struct {
 	io.Reader
 	io.Writer
@@ -28,6 +33,7 @@ func main() {
 		panic(err)
 	}
 
+	// allocate the low-level frame.ReadWriter around a io.ReadWriter
 	rw, err := frame.NewReadWriter(frame.ReadWriterConf{
 		ReadWriter: &readWriter{
 			Reader: inBuf,
@@ -41,15 +47,15 @@ func main() {
 		panic(err)
 	}
 
-	// read a message (wrapped in a frame)
+	// read a frame, that contains a message
 	frame, err := rw.Read()
 	if err != nil {
 		panic(err)
 	}
 
 	log.Printf("decoded: %+v\n", frame)
 
-	// write a message
+	// write a message, that is automatically wrapped in a frame
 	err = rw.WriteMessage(&ardupilotmega.MessageParamValue{
 		ParamId:    "test_parameter",
 		ParamValue: 123456,