diff --git a/examples/example/src/main.rs b/examples/example/src/main.rs
index b8bb209..1be4644 100644
--- a/examples/example/src/main.rs
+++ b/examples/example/src/main.rs
@@ -10,10 +10,7 @@ use crate::org_example_network::VarlinkClientInterface;
 // Using the `varlink_derive::varlink_file!` macro has the drawback,
 // that most IDEs don't execute this and thus offer no code completion.
 // Better use a `build.rs` as the other examples.
-varlink_derive::varlink_file!(
-    org_example_network,
-    "examples/example/src/org.example.network.varlink"
-);
+varlink_derive::varlink_file!(org_example_network, "src/org.example.network.varlink");
 
 #[cfg(test)]
 mod test;
diff --git a/varlink-certification/src/test.rs b/varlink-certification/src/test.rs
index 0cd4c96..f296c48 100644
--- a/varlink-certification/src/test.rs
+++ b/varlink-certification/src/test.rs
@@ -4,11 +4,9 @@ use varlink::Connection;
 
 pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;
 
-fn run_self_test(address: String) -> Result<()> {
-    let client_address = address.clone();
-
+fn run_self_test(address: &'static str) -> Result<()> {
     let child = thread::spawn(move || {
-        if let Err(e) = crate::run_server(&address, 4) {
+        if let Err(e) = crate::run_server(address, 4) {
             match e.kind() {
                 ::varlink::ErrorKind::Timeout => {}
                 _ => panic!("error: {:#?}", e),
@@ -19,7 +17,7 @@ fn run_self_test(address: String) -> Result<()> {
     // give server time to start
     thread::sleep(time::Duration::from_secs(1));
 
-    let ret = crate::run_client(Connection::with_address(&client_address)?);
+    let ret = crate::run_client(Connection::with_address(address)?);
     if let Err(e) = ret {
         panic!("error: {:?}", e);
     }
@@ -32,21 +30,21 @@ fn run_self_test(address: String) -> Result<()> {
 
 #[test]
 fn test_unix() -> crate::Result<()> {
-    run_self_test("unix:org.varlink.certification".into())
+    run_self_test("unix:org.varlink.certification")
 }
 
 #[test]
 #[cfg(any(target_os = "linux", target_os = "android"))]
 fn test_unix_abstract() -> Result<()> {
-    run_self_test("unix:@org.varlink.certification_abs".into())
+    run_self_test("unix:@org.varlink.certification_abs")
 }
 
 #[test]
 fn test_tcp() -> Result<()> {
-    run_self_test("tcp:127.0.0.1:23456".into())
+    run_self_test("tcp:127.0.0.1:23456")
 }
 
 #[test]
 fn test_wrong_address_1() {
-    assert!(crate::run_server("tcpd:0.0.0.0:12345", 1).is_err());
+    crate::run_server("tcpd:0.0.0.0:12345", 1).unwrap_err();
 }
diff --git a/varlink/Cargo.toml b/varlink/Cargo.toml
index 448bf11..6f3495a 100644
--- a/varlink/Cargo.toml
+++ b/varlink/Cargo.toml
@@ -41,3 +41,5 @@ libc = { version = "0.2.126", default-features = false }
 
 [dev-dependencies]
 static_assertions = "1.1.0"
+varlink_derive = { version = "10.1", path = "../varlink_derive" }
+varlink_generator = { version = "11.0", path = "../varlink_generator" }
diff --git a/varlink/src/lib.rs b/varlink/src/lib.rs
index 9508b4a..069b42a 100644
--- a/varlink/src/lib.rs
+++ b/varlink/src/lib.rs
@@ -15,7 +15,7 @@
 //!
 //! Then create a `build.rs` file in your project directory:
 //!
-//! ```rust,ignore
+//! ```rust,no_run
 //! extern crate varlink_generator;
 //!
 //! fn main() {
@@ -180,7 +180,7 @@
 //! # fn main() {}
 //! ```
 //!
-//! where args[1] would follow the varlink
+//! where `args[1]` would follow the varlink
 //! [address specification](https://github.com/varlink/documentation/wiki#address).
 //!
 //! Currently supported address URIs are:
@@ -196,13 +196,28 @@
 //!
 //! In your `main.rs` you can then use:
 //!
-//! ```rust,ignore
-//! mod org_example_ping;
-//! use org_example_ping;
+//! ```rust,no_run
+//! extern crate serde_derive;
+//!
+//! use varlink_derive;
+//! use varlink::Connection;
+//!
+//! varlink_derive::varlink!(org_example_ping, r#"
+//! ## Example service
+//! interface org.example.ping
+//!
+//! ## Returns the same string
+//! method Ping(ping: string) -> (pong: string)
+//! "#);
+//! use org_example_ping::VarlinkClientInterface;
+//!
+//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
 //! let connection = Connection::with_address("unix:/tmp/org.example.ping").unwrap();
 //! let mut ping_service = org_example_ping::VarlinkClient::new(connection);
 //! let reply = ping_service.ping(String::from("Test")).call()?;
 //! assert_eq!(String::from("Test"), reply.pong);
+//! # Ok(())
+//! # }
 //! ```
 //!
 //! A connection can be established via the [`connection builder`] functions.
@@ -834,7 +849,8 @@ impl Connection {
     ///
     /// # Examples
     ///
-    /// ```rust,ignore
+    /// ```rust,no_run
+    /// # use varlink::Connection;
     /// let connection = Connection::with_address("unix:/tmp/org.example.myservice");
     /// let connection = Connection::with_address("tcp:127.0.0.1:12345");
     /// ```
@@ -873,7 +889,8 @@ impl Connection {
     ///
     /// # Examples
     ///
-    /// ```rust,ignore
+    /// ```rust,no_run
+    /// # use varlink::Connection;
     /// let connection = Connection::with_activate("myservice --varlink=$VARLINK_ADDRESS");
     /// ```
     pub fn with_activate<S: ?Sized + AsRef<str>>(command: &S) -> Result<Arc<RwLock<Self>>> {
@@ -915,7 +932,8 @@ impl Connection {
     ///
     /// # Examples
     ///
-    /// ```rust,ignore
+    /// ```rust,no_run
+    /// # use varlink::Connection;
     /// let connection = Connection::with_bridge("ssh my.example.org -- varlink bridge");
     /// ```
     pub fn with_bridge<S: ?Sized + AsRef<str>>(command: &S) -> Result<Arc<RwLock<Self>>> {
diff --git a/varlink_derive/Cargo.toml b/varlink_derive/Cargo.toml
index 2341e92..c8ea628 100644
--- a/varlink_derive/Cargo.toml
+++ b/varlink_derive/Cargo.toml
@@ -17,3 +17,9 @@ path = "src/lib.rs"
 
 [dependencies]
 varlink_generator = { version = "11.0", path = "../varlink_generator" }
+
+[dev-dependencies]
+serde = "1.0.102"
+serde_derive = "1.0.102"
+serde_json = "1.0.41"
+varlink = { version = "11.0", path = "../varlink" }
diff --git a/varlink_derive/src/lib.rs b/varlink_derive/src/lib.rs
index bae8e63..05e17aa 100644
--- a/varlink_derive/src/lib.rs
+++ b/varlink_derive/src/lib.rs
@@ -1,34 +1,43 @@
-//! Macro for generating modules from a varlink interface definition
+//! Macros for generating modules from a varlink interface definition
 //!
-//! It has the drawback, that most IDEs don't execute this and thus
+//! This crate provides two procedural macros for generating a Rust module out of an interface
+//! definition:
+//!
+//! - The [`varlink!`] macro takes as argument the interface as a string literal.
+//! - The [`varlink_file!`] macro takes as argument the path to the varlink interface definition
+//!   _relative_ to the directory containing the manifest of your package.
+//!
+//! They have the drawback that most IDEs don't execute this and thus
 //! offer no code completion.
 //!
-//! Examples:
+//! # Examples
 //!
-//! ```rust,ignore
+//! ```rust,no_run
 //! use varlink_derive;
+//! extern crate serde_derive;
 //!
 //! varlink_derive::varlink!(org_example_ping, r#"
-//! # Example service
+//! ## Example service
 //! interface org.example.ping
 //!
-//! # Returns the same string
+//! ## Returns the same string
 //! method Ping(ping: string) -> (pong: string)
 //! "#);
 //!
-//! use crate::org_example_ping::VarlinkClientInterface;
+//! use org_example_ping::VarlinkClientInterface;
 //! /* ... */
 //! ```
 //!
-//! ```rust,ignore
+//! ```rust,no_run
 //! use varlink_derive;
+//! extern crate serde_derive;
 //!
 //! varlink_derive::varlink_file!(
 //!    org_example_network,
-//!    "examples/example/src/org.example.network.varlink"
+//!    "../examples/example/src/org.example.network.varlink"
 //! );
 //!
-//! use crate::org_example_network::VarlinkClientInterface;
+//! use org_example_network::VarlinkClientInterface;
 //! /* ... */
 //! ```
 
@@ -40,22 +49,28 @@ use std::io::Read;
 
 /// Generates a module from a varlink interface definition
 ///
-/// `varlink!(<modulename>, r#"<varlink interface definition>"#)`
+/// # Usage
+///
+/// The macro takes two arguments:
 ///
-/// Examples:
+/// 1. The module name that will be generated. It must be a valid Rust identifier.
+/// 2. A string literal containing the the varlink interface definition.
 ///
-/// ```rust,ignore
+/// # Examples
+///
+/// ```rust,no_run
 /// use varlink_derive;
-//
+/// extern crate serde_derive;
+///
 /// varlink_derive::varlink!(org_example_ping, r#"
-/// # Example service
+/// ## Example service
 /// interface org.example.ping
 ///
-/// # Returns the same string
+/// ## Returns the same string
 /// method Ping(ping: string) -> (pong: string)
 /// "#);
 ///
-/// use crate::org_example_ping::VarlinkClientInterface;
+/// use org_example_ping::VarlinkClientInterface;
 /// /* ... */
 /// ```
 #[proc_macro]
@@ -66,29 +81,56 @@ pub fn varlink(input: TokenStream) -> TokenStream {
 
 /// Generates a module from a varlink interface definition file
 ///
-/// `varlink!(<modulename>, "<varlink interface definition file path relative to the workspace>")`
+/// # Usage
+///
+/// The macro takes two arguments:
 ///
-/// Examples:
+/// 1. The module name that will be generated. It must be a valid Rust identifier.
+/// 2. A string literal containing the file path of the varlink interface definition. The path
+///    **must** be relative to the directory containing the manifest of your package.
 ///
-/// ```rust,ignore
+/// # Examples
+///
+/// ```rust,no_run
 /// use varlink_derive;
+/// extern crate serde_derive;
 ///
 /// varlink_derive::varlink_file!(
 ///    org_example_network,
-///    "examples/example/src/org.example.network.varlink"
+///    "../examples/example/src/org.example.network.varlink"
 ///);
 ///
-/// use crate::org_example_network::VarlinkClientInterface;
+/// use org_example_network::VarlinkClientInterface;
 /// /* ... */
 /// ```
 #[proc_macro]
 pub fn varlink_file(input: TokenStream) -> TokenStream {
     let (name, filename, _) = parse_varlink_filename_args(input);
     let mut source = Vec::<u8>::new();
-    std::fs::File::open(filename)
-        .unwrap()
+
+    let path = if let Some(manifest_dir) = std::env::var_os("CARGO_MANIFEST_DIR") {
+        std::borrow::Cow::Owned(std::path::Path::new(&manifest_dir).join(filename))
+    } else {
+        std::borrow::Cow::Borrowed(std::path::Path::new(&filename))
+    };
+
+    std::fs::File::open(&path)
+        .unwrap_or_else(|err| {
+            panic!(
+                "varlink_file! expansion failed. Could not open file {}: {}",
+                path.display(),
+                err
+            )
+        })
         .read_to_end(&mut source)
-        .unwrap();
+        .unwrap_or_else(|err| {
+            panic!(
+                "varlink_file! expansion failed. Could not read file {}: {}",
+                path.display(),
+                err
+            )
+        });
+
     expand_varlink(name, String::from_utf8_lossy(&source).to_string())
 }
 
diff --git a/varlink_generator/src/bin/varlink-rust-generator.rs b/varlink_generator/src/bin/varlink-rust-generator.rs
index 14536f5..f745089 100644
--- a/varlink_generator/src/bin/varlink-rust-generator.rs
+++ b/varlink_generator/src/bin/varlink-rust-generator.rs
@@ -3,11 +3,11 @@
 //!
 //! # Usage
 //!
-//! ~~~norun
+//! ```shell
 //! $ varlink-rust-generator `[<varlink_file>]`
-//! ~~~
+//! ```
 //!
-//! If <varlink_file> is omitted, input is expected to come from stdin.
+//! If `<varlink_file>` is omitted, input is expected to come from stdin.
 //!
 //! Output is sent to stdout.
 
diff --git a/varlink_generator/src/lib.rs b/varlink_generator/src/lib.rs
index 78ed48d..b17fb63 100644
--- a/varlink_generator/src/lib.rs
+++ b/varlink_generator/src/lib.rs
@@ -15,7 +15,7 @@
 //!
 //! Then create a `build.rs` file in your project directory using [`varlink_generator::cargo_build_tosource`]:
 //!
-//! ```rust,ignore
+//! ```rust,no_run
 //! extern crate varlink_generator;
 //!
 //! fn main() {
diff --git a/varlink_stdinterfaces/src/org.varlink.resolver.varlink b/varlink_stdinterfaces/src/org.varlink.resolver.varlink
index a7297e7..5be371c 100644
--- a/varlink_stdinterfaces/src/org.varlink.resolver.varlink
+++ b/varlink_stdinterfaces/src/org.varlink.resolver.varlink
@@ -1,5 +1,5 @@
 # Interface to resolve reverse-domain interface names to
-# service adresses
+# service addresses
 interface org.varlink.resolver
 
 # Get a list of all resolvable interfaces and information