From 3fa13e7aed8c8dd649728812a618db65350a6700 Mon Sep 17 00:00:00 2001
From: tison <wander4096@gmail.com>
Date: Tue, 12 Nov 2024 11:16:29 +0800
Subject: [PATCH] docs: integrate with log and others

Signed-off-by: tison <wander4096@gmail.com>
---
 Cargo.toml        | 16 ++++++++++++++++
 README.md         | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 src/sender/mod.rs |  8 ++++++++
 3 files changed, 70 insertions(+)

diff --git a/Cargo.toml b/Cargo.toml
index 7a3ca25..340ae3e 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -42,3 +42,19 @@ windows-targets = { version = "0.52.6" }
 
 [dev-dependencies]
 names = { version = "0.14.0", default-features = false }
+
+
+[[example]]
+doc-scrape-examples = true
+name = "tcp_sender"
+path = "examples/tcp_sender.rs"
+
+[[example]]
+doc-scrape-examples = true
+name = "udp_sender"
+path = "examples/udp_sender.rs"
+
+[[example]]
+doc-scrape-examples = true
+name = "unix_sender"
+path = "examples/unix_sender.rs"
diff --git a/README.md b/README.md
index 36a604a..ea64a23 100644
--- a/README.md
+++ b/README.md
@@ -34,6 +34,52 @@ Add `fasyslog` to your `Cargo.toml`:
 cargo add fasyslog
 ```
 
+```rust
+use fasyslog::Severity;
+
+fn main() {
+    let mut sender = fasyslog::sender::tcp_well_known().unwrap();
+    let message = format!("Hello, fasyslog!");
+    // send a message with RFC 3164 format
+    sender.send_rfc3164(Severity::ERROR, message).unwrap();
+    sender.flush().unwrap();
+
+    // send a message with RFC 5424 format
+    const EMPTY_MSGID: Option<&str> = None;
+    const EMPTY_STRUCTURED_DATA: Vec<fasyslog::SDElement> = Vec::new();
+    sender.send_rfc5424(Severity::ERROR, EMPTY_MSGID, EMPTY_STRUCTURED_DATA, message).unwrap();
+    sender.flush().unwrap();
+}
+```
+
+If you'd like to integrate with `log` crate, you can try the `logforth` example:
+
+```toml
+[dependencies]
+log = { version = "..." }
+logforth = { version = "...", features = ["syslog"] }
+```
+
+```rust
+use logforth::append::syslog;
+use logforth::append::syslog::Syslog;
+use logforth::append::syslog::SyslogWriter;
+
+fn main() {
+    let syslog_writer = SyslogWriter::tcp_well_known().unwrap();
+    let (non_blocking, _guard) = syslog::non_blocking_builder().finish(syslog_writer);
+
+    logforth::builder()
+        .dispatch(|d| {
+            d.filter(log::LevelFilter::Trace)
+                .append(Syslog::new(non_blocking))
+        })
+        .apply();
+
+    log::info!("This log will be written to syslog.");
+}
+```
+
 ## Example
 
 Check the [examples](examples) directory for more examples.
diff --git a/src/sender/mod.rs b/src/sender/mod.rs
index 8badd0c..285f88d 100644
--- a/src/sender/mod.rs
+++ b/src/sender/mod.rs
@@ -96,6 +96,14 @@ impl SyslogSender {
     }
 
     /// Flush the underlying writer if needed.
+    ///
+    /// When the underlying writer is a streaming writer (TCP, UnixStream, etc.), periodically
+    /// flush is essential to ensure that the message is sent to the syslog server [1].
+    ///
+    /// When the underlying writer is a datagram writer (UDP, UnixDatagram, etc.), flush is a no-op,
+    /// and every call to `send_xxx` defines the boundary of the packet.
+    ///
+    /// [1]: https://github.com/Geal/rust-syslog/issues/69
     pub fn flush(&mut self) -> io::Result<()> {
         match self {
             SyslogSender::Tcp(sender) => sender.flush(),