docs: Update Flush documentation

client.go

@@ -266,8 +266,17 @@ func (client *Client) RecoverWithContext(
 	return nil
 }
 
-// Flush notifies when all the buffered events have been sent by returning `true`
-// or `false` if timeout was reached. It calls `Flush` method of the configured `Transport`.
+// Flush waits until the underlying Transport sends any buffered events to the
+// Sentry server, blocking for at most the given timeout. It returns false if
+// the timeout was reached. In that case, some events may not have been sent.
+//
+// Flush should be called before terminating the program to avoid
+// unintentionally dropping events.
+//
+// Do not call Flush indiscriminately after every call to CaptureEvent,
+// CaptureException or CaptureMessage. Instead, to have the SDK send events over
+// the network synchronously, configure it to use the HTTPSyncTransport in the
+// call to Init.
 func (client *Client) Flush(timeout time.Duration) bool {
 	return client.Transport.Flush(timeout)
 }

hub.go

@@ -322,7 +322,17 @@ func (hub *Hub) RecoverWithContext(ctx context.Context, err interface{}) *EventI
 	return client.RecoverWithContext(ctx, err, &EventHint{RecoveredException: err}, scope)
 }
 
-// Flush calls the method of a same name on currently bound `Client` instance.
+// Flush waits until the underlying Transport sends any buffered events to the
+// Sentry server, blocking for at most the given timeout. It returns false if
+// the timeout was reached. In that case, some events may not have been sent.
+//
+// Flush should be called before terminating the program to avoid
+// unintentionally dropping events.
+//
+// Do not call Flush indiscriminately after every call to CaptureEvent,
+// CaptureException or CaptureMessage. Instead, to have the SDK send events over
+// the network synchronously, configure it to use the HTTPSyncTransport in the
+// call to Init.
 func (hub *Hub) Flush(timeout time.Duration) bool {
 	client := hub.Client()
 

sentry.go

@@ -112,8 +112,17 @@ func PopScope() {
 	hub.PopScope()
 }
 
-// Flush notifies when all the buffered events have been sent by returning `true`
-// or `false` if timeout was reached.
+// Flush waits until the underlying Transport sends any buffered events to the
+// Sentry server, blocking for at most the given timeout. It returns false if
+// the timeout was reached. In that case, some events may not have been sent.
+//
+// Flush should be called before terminating the program to avoid
+// unintentionally dropping events.
+//
+// Do not call Flush indiscriminately after every call to CaptureEvent,
+// CaptureException or CaptureMessage. Instead, to have the SDK send events over
+// the network synchronously, configure it to use the HTTPSyncTransport in the
+// call to Init.
 func Flush(timeout time.Duration) bool {
 	hub := CurrentHub()
 	return hub.Flush(timeout)

transport.go

@@ -224,8 +224,16 @@ func (t *HTTPTransport) SendEvent(event *Event) {
 	t.buffer <- b
 }
 
-// Flush notifies when all the buffered events have been sent by returning `true`
-// or `false` if timeout was reached.
+// Flush waits until any buffered events are sent to the Sentry server, blocking
+// for at most the given timeout. It returns false if the timeout was reached.
+// In that case, some events may not have been sent.
+//
+// Flush should be called before terminating the program to avoid
+// unintentionally dropping events.
+//
+// Do not call Flush indiscriminately after every call to SendEvent. Instead, to
+// have the SDK send events over the network synchronously, configure it to use
+// the HTTPSyncTransport in the call to Init.
 func (t *HTTPTransport) Flush(timeout time.Duration) bool {
 	toolate := time.After(timeout)
 
@@ -400,8 +408,7 @@ func (t *HTTPSyncTransport) SendEvent(event *Event) {
 	}
 }
 
-// Flush notifies when all the buffered events have been sent by returning `true`
-// or `false` if timeout was reached. No-op for HTTPSyncTransport.
+// Flush is a no-op for HTTPSyncTransport. It always returns true immediately.
 func (t *HTTPSyncTransport) Flush(_ time.Duration) bool {
 	return true
 }