improve sophia_api::ns documentation

api/src/ns.rs

@@ -2,9 +2,9 @@
 //!
 //! This module provides:
 //! * the [`Namespace`](struct.Namespace.html) type for defining custom dynamic namespace;
-//! * the [`namespace`] macro, for defning custom static namespaces;
+//! * the [`namespace`](crate::namespace) macro, for defning custom static namespaces;
 //! * modules corresponding to the most common namespaces
-//!   (generated via the [`namespace`] macro).
+//!   (generated via the [`namespace`](crate::namespace) macro).
 //!
 //! # Example use
 //! ```
@@ -21,8 +21,8 @@
 //!
 //! # Datatyped literals
 //!
-//! Note also that the terms generated via the [`namespace`] macro
-//! can be used to easily produced datatyped literals,
+//! Note also that the terms generated via the [`namespace`](crate::namespace) macro
+//! can be used to easily produce datatyped literals,
 //! by simply "multiplying" a string by its datatype:
 //!
 //! ```

api/src/ns/_macro.rs

@@ -5,6 +5,24 @@
 /// This macro also create a test module to check that all created IRIs are valid.
 ///
 /// This allows to skip those checks at runtime, keeping the initialization of the namespace fast.
+///
+/// # Example
+/// ```
+/// # #[macro_use] extern crate sophia_api;
+/// # use sophia_iri::IriRef;
+/// /// An example namespace module
+/// pub mod ex {
+///   namespace! {
+///     "http://example.org/ns#",
+///     Foo,
+///     Bar,
+///     Baz
+///   }
+/// }
+///
+/// assert_eq!(ex::Foo, IriRef::new_unchecked("http://example.org/ns#Foo"));
+/// assert_eq!(ex::Bar, IriRef::new_unchecked("http://example.org/ns#Bar"));
+/// ```
 #[macro_export]
 macro_rules! namespace {
     ($iri_prefix:expr, $($suffix:ident),*; $($r_id:ident, $r_sf:expr),*) => {