From 9316eb07ac2d481b654f8855b74e379fc3a98a7f Mon Sep 17 00:00:00 2001
From: Pierre-Antoine Champin <pierre-antoine@w3.org>
Date: Wed, 15 Nov 2023 16:19:57 +0100
Subject: [PATCH] improve sophia_api::ns documentation

---
 api/src/ns.rs        |  8 ++++----
 api/src/ns/_macro.rs | 18 ++++++++++++++++++
 2 files changed, 22 insertions(+), 4 deletions(-)

diff --git a/api/src/ns.rs b/api/src/ns.rs
index 39e8c679..141b0a2c 100644
--- a/api/src/ns.rs
+++ b/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:
 //!
 //! ```
diff --git a/api/src/ns/_macro.rs b/api/src/ns/_macro.rs
index 84535e70..623ebb6d 100644
--- a/api/src/ns/_macro.rs
+++ b/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),*) => {