network: clean up docs

diff --git a/network/src/lib.rs b/network/src/lib.rs
index 16b80ad6..7e96de35 100644
--- a/network/src/lib.rs
+++ b/network/src/lib.rs
@@ -1,10 +1,23 @@
 // SPDX-License-Identifier: CC0-1.0
 
-//! # Bitcoin network
+//! # Rust Bitcoin Network Kind
 //!
 //! The term "network" is overloaded, here [`Network`] refers to the specific
 //! Bitcoin network we are operating on e.g., signet, regtest. The terms
 //! "network" and "chain" are often used interchangeably for this concept.
+//!
+//! # Exhaustivity
+//!
+//! The [`Network`] enum is exhaustive by design. New Bitcoin networks require a breaking change
+//! to this enum, which forces library users to explicitly handle them. In contrast,
+//! [`TestnetVersion`] uses `#[non_exhaustive]` since testnet versions evolve more frequently.
+//!
+//! If you're concerned about forward compatibility with potential future Bitcoin networks, the
+//! higher level `bitcoin` crate provides a `Params` type that encapsulates network-specific
+//! parameters. Consider using `T: Into<Params>` in your public APIs instead of [`Network`]
+//! directly.
+//!
+//! See [issue #2225](https://github.com/rust-bitcoin/rust-bitcoin/issues/2225) for more discussion.
 
 #![no_std]
 // Coding conventions.
@@ -42,7 +55,7 @@ pub enum NetworkKind {
 }
 
 impl NetworkKind {
-    /// Returns true if this is real mainnet bitcoin.
+    /// Returns `true` if this represents the Bitcoin mainnet.
     pub const fn is_mainnet(self) -> bool { matches!(self, Self::Main) }
 }
 
@@ -55,16 +68,15 @@ impl From<Network> for NetworkKind {
     }
 }
 
-/// The cryptocurrency network to act on.
+/// The Bitcoin network to act on.
 ///
 /// This is an exhaustive enum, meaning that we cannot add any future networks without defining a
-/// new, incompatible version of this type. If you are using this type directly and wish to support the
-/// new network, this will be a breaking change to your APIs and likely require changes in your code.
+/// new, incompatible version of this type. If you are using this type directly and wish to support
+/// the new network, this will be a breaking change to your APIs and likely require changes in your
+/// code.
 ///
-/// If you are concerned about forward compatibility, consider using `T: Into<Params>` instead of
-/// this type as a parameter to functions in your public API, or directly using the `Params` type.
-// For extensive discussion on the usage of `non_exhaustive` please see:
-// https://github.com/rust-bitcoin/rust-bitcoin/issues/2225
+/// For forward compatibility, consider using the `Params` type from the higher level `bitcoin`
+/// crate instead.
 #[derive(Copy, PartialEq, Eq, PartialOrd, Ord, Clone, Hash, Debug)]
 pub enum Network {
     /// Mainnet Bitcoin.
@@ -125,15 +137,10 @@ impl<'de> Deserialize<'de> for Network {
 }
 
 impl Network {
-    /// Converts a `Network` to its equivalent `bitcoind -chain` argument name.
-    ///
-    /// ```bash
-    /// $ bitcoin-23.0/bin/bitcoind --help | grep -C 3 '\-chain=<chain>'
-    /// Chain selection options:
+    /// Converts to the equivalent Bitcoin Core `-chain` argument string.
     ///
-    /// -chain=<chain>
-    /// Use the chain <chain> (default: main). Allowed values: main, test, signet, regtest
-    /// ```
+    /// This is useful when interacting with Bitcoin Core via command-line arguments or
+    /// configuration files that expect the `-chain` parameter format.
     pub fn to_core_arg(self) -> &'static str {
         match self {
             Self::Bitcoin => "main",
@@ -145,24 +152,18 @@ impl Network {
         }
     }
 
-    /// Converts a `bitcoind -chain` argument name to its equivalent `Network`.
+    /// Parses a Bitcoin Core `-chain` argument string into a `Network`.
+    ///
+    /// This is the inverse of [`to_core_arg`](Self::to_core_arg), useful when parsing
+    /// configuration files or command-line arguments from Bitcoin Core.
     ///
-    /// ```bash
-    /// $ bitcoin-23.0/bin/bitcoind --help | grep -C 3 '\-chain=<chain>'
-    /// Chain selection options:
+    /// # Arguments
     ///
-    /// -chain=<chain>
-    /// Use the chain <chain> (default: main). Allowed values: main, test, signet, regtest
-    /// ```
+    /// * `core_arg` - A string value from Bitcoin Core's `-chain` parameter.
     ///
     /// # Errors
     ///
-    /// Errors if input is not exactly one of:
-    /// * `main`
-    /// * `test`
-    /// * `testnet4`
-    /// * `signet`
-    /// * `regtest`
+    /// Returns [`ParseNetworkError`] if the input is not a valid network identifier.
     pub fn from_core_arg(core_arg: &str) -> Result<Self, ParseNetworkError> {
         let network = match core_arg {
             "main" => Self::Bitcoin,
@@ -175,8 +176,7 @@ impl Network {
         Ok(network)
     }
 
-    /// Returns a string representation of the `Network` enum variant.
-    /// This is useful for displaying the network type as a string.
+    /// Returns the standard display string for this network.
     const fn as_display_str(self) -> &'static str {
         match self {
             Self::Bitcoin => "bitcoin",
@@ -196,7 +196,24 @@ impl fmt::Display for Network {
 
 #[cfg(feature = "serde")]
 pub mod as_core_arg {
-    //! Module for serialization/deserialization of network variants into/from Bitcoin Core values
+    //! Serde helper module for Bitcoin Core `-chain` argument serialization.
+    //!
+    //! This module provides custom serialization/deserialization for use with the
+    //! `#[serde(with = "...")]` attribute, converting [`Network`] to/from the Bitcoin Core
+    //! `-chain` argument format.
+    //!
+    //! # Example
+    //!
+    //! ```ignore
+    //! use serde::{Deserialize, Serialize};
+    //! use bitcoin_network_kind::Network;
+    //!
+    //! #[derive(Serialize, Deserialize)]
+    //! struct Config {
+    //!     #[serde(with = "bitcoin_network_kind::as_core_arg")]
+    //!     network: Network,
+    //! }
+    //! ```
 
     // No need to document these functions, they are well known.
     #![allow(missing_docs)]
@@ -245,6 +262,7 @@ pub mod as_core_arg {
 impl FromStr for Network {
     type Err = ParseNetworkError;
 
+    /// Parses a network identifier string into a `Network`.
     #[inline]
     fn from_str(s: &str) -> Result<Self, Self::Err> {
         match s {