Make features linkable and reference them in the docs

Changelog.md

@@ -26,9 +26,11 @@ MSRV bumped to 1.56! Crate now uses Rust 2021 edition.
 - [#545]: Added new `Error` variant -- `Error::InvalidPrefixBind`.
 - [#651]: Relax requirement for version of `arbitrary` dependency -- we're actually
   compatible with version 1.0.0 and up.
+- [#649]: Make features linkable and reference them in the docs.
 
 [#545]: https://github.com/tafia/quick-xml/pull/545
 [#643]: https://github.com/tafia/quick-xml/pull/643
+[#649]: https://github.com/tafia/quick-xml/pull/646
 [#651]: https://github.com/tafia/quick-xml/pull/651
 
 

src/de/map.rs

@@ -646,11 +646,13 @@ where
     map: &'m mut MapAccess<'de, 'a, R, E>,
     /// Filter that determines whether a tag is a part of this sequence.
     ///
-    /// When feature `overlapped-lists` is not activated, iteration will stop
+    /// When feature [`overlapped-lists`] is not activated, iteration will stop
     /// when found a tag that does not pass this filter.
     ///
-    /// When feature `overlapped-lists` is activated, all tags, that not pass
+    /// When feature [`overlapped-lists`] is activated, all tags, that not pass
     /// this check, will be skipped.
+    ///
+    /// [`overlapped-lists`]: ../../index.html#overlapped-lists
     filter: TagFilter<'de>,
 
     /// Checkpoint after which all skipped events should be returned. All events,

src/encoding.rs

@@ -23,17 +23,18 @@ pub(crate) const UTF16_BE_BOM: &[u8] = &[0xFE, 0xFF];
 
 /// Decoder of byte slices into strings.
 ///
-/// If feature `encoding` is enabled, this encoding taken from the `"encoding"`
+/// If feature [`encoding`] is enabled, this encoding taken from the `"encoding"`
 /// XML declaration or assumes UTF-8, if XML has no <?xml ?> declaration, encoding
 /// key is not defined or contains unknown encoding.
 ///
 /// The library supports any UTF-8 compatible encodings that crate `encoding_rs`
 /// is supported. [*UTF-16 and ISO-2022-JP are not supported at the present*][utf16].
 ///
-/// If feature `encoding` is disabled, the decoder is always UTF-8 decoder:
+/// If feature [`encoding`] is disabled, the decoder is always UTF-8 decoder:
 /// any XML declarations are ignored.
 ///
 /// [utf16]: https://github.com/tafia/quick-xml/issues/158
+/// [`encoding`]: ../index.html#encoding
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub struct Decoder {
     #[cfg(feature = "encoding")]

src/errors.rs

@@ -16,8 +16,10 @@ pub enum Error {
     ///
     /// `Arc<IoError>` instead of `IoError` since `IoError` is not `Clone`.
     Io(Arc<IoError>),
-    /// Input decoding error. If `encoding` feature is disabled, contains `None`,
+    /// Input decoding error. If [`encoding`] feature is disabled, contains `None`,
     /// otherwise contains the UTF-8 decoding error
+    ///
+    /// [`encoding`]: index.html#encoding
     NonDecodable(Option<Utf8Error>),
     /// Unexpected End of File
     UnexpectedEof(String),

src/escapei.rs

@@ -144,8 +144,9 @@ pub(crate) fn _escape<F: Fn(u8) -> bool>(raw: &str, escape_chars: F) -> Cow<str>
 /// Unescape an `&str` and replaces all xml escaped characters (`&...;`) into
 /// their corresponding value.
 ///
-/// If feature `escape-html` is enabled, then recognizes all [HTML5 escapes].
+/// If feature [`escape-html`] is enabled, then recognizes all [HTML5 escapes].
 ///
+/// [`escape-html`]: ../index.html#escape-html
 /// [HTML5 escapes]: https://dev.w3.org/html5/html-author/charref
 pub fn unescape(raw: &str) -> Result<Cow<str>, EscapeError> {
     unescape_with(raw, |_| None)
@@ -154,8 +155,9 @@ pub fn unescape(raw: &str) -> Result<Cow<str>, EscapeError> {
 /// Unescape an `&str` and replaces all xml escaped characters (`&...;`) into
 /// their corresponding value, using a resolver function for custom entities.
 ///
-/// If feature `escape-html` is enabled, then recognizes all [HTML5 escapes].
+/// If feature [`escape-html`] is enabled, then recognizes all [HTML5 escapes].
 ///
+/// [`escape-html`]: ../index.html#escape-html
 /// [HTML5 escapes]: https://dev.w3.org/html5/html-author/charref
 pub fn unescape_with<'input, 'entity, F>(
     raw: &'input str,

src/events/attributes.rs

@@ -39,7 +39,9 @@ impl<'a> Attribute<'a> {
     ///
     /// See also [`unescape_value_with()`](Self::unescape_value_with)
     ///
-    /// This method is available only if `encoding` feature is **not** enabled.
+    /// This method is available only if [`encoding`] feature is **not** enabled.
+    ///
+    /// [`encoding`]: ../../index.html#encoding
     #[cfg(any(doc, not(feature = "encoding")))]
     pub fn unescape_value(&self) -> XmlResult<Cow<'a, str>> {
         self.unescape_value_with(|_| None)
@@ -56,7 +58,9 @@ impl<'a> Attribute<'a> {
     ///
     /// See also [`unescape_value()`](Self::unescape_value)
     ///
-    /// This method is available only if `encoding` feature is **not** enabled.
+    /// This method is available only if [`encoding`] feature is **not** enabled.
+    ///
+    /// [`encoding`]: ../../index.html#encoding
     #[cfg(any(doc, not(feature = "encoding")))]
     pub fn unescape_value_with<'entity>(
         &self,

src/lib.rs

@@ -17,11 +17,11 @@
 //! in the XML document the current event is located.
 //!
 //! quick-xml contains optional support of asynchronous reading and writing using [tokio].
-//! To get it enable the `async-tokio` feature.
+//! To get it enable the [`async-tokio`](#async-tokio) feature.
 //!
 //! Furthermore, quick-xml also contains optional [Serde] support to directly
 //! serialize and deserialize from structs, without having to deal with the XML events.
-//! To get it enable the `serialize` feature. Read more about mapping Rust types
+//! To get it enable the [`serialize`](#serialize) feature. Read more about mapping Rust types
 //! to XML in the documentation of [`de`] module. Also check [`serde_helpers`]
 //! module.
 //!
@@ -40,7 +40,9 @@
 //! [`de`]: ./de/index.html
 #![cfg_attr(
     feature = "document-features",
-    cfg_attr(doc, doc = ::document_features::document_features!())
+    cfg_attr(doc, doc = ::document_features::document_features!(
+        feature_label = "<a id=\"{feature}\" href=\"#{feature}\"><strong><code>{feature}</code></strong></a>"
+    ))
 )]
 #![forbid(unsafe_code)]
 #![deny(missing_docs)]

src/reader/mod.rs

@@ -624,11 +624,13 @@ impl<R> Reader<R> {
 
     /// Get the decoder, used to decode bytes, read by this reader, to the strings.
     ///
-    /// If `encoding` feature is enabled, the used encoding may change after
+    /// If [`encoding`] feature is enabled, the used encoding may change after
     /// parsing the XML declaration, otherwise encoding is fixed to UTF-8.
     ///
-    /// If `encoding` feature is enabled and no encoding is specified in declaration,
+    /// If [`encoding`] feature is enabled and no encoding is specified in declaration,
     /// defaults to UTF-8.
+    ///
+    /// [`encoding`]: ../index.html#encoding
     #[inline]
     pub fn decoder(&self) -> Decoder {
         self.parser.decoder()

src/reader/parser.rs

@@ -250,11 +250,13 @@ impl Parser {
 
     /// Get the decoder, used to decode bytes, read by this reader, to the strings.
     ///
-    /// If `encoding` feature is enabled, the used encoding may change after
+    /// If [`encoding`] feature is enabled, the used encoding may change after
     /// parsing the XML declaration, otherwise encoding is fixed to UTF-8.
     ///
-    /// If `encoding` feature is enabled and no encoding is specified in declaration,
+    /// If [`encoding`] feature is enabled and no encoding is specified in declaration,
     /// defaults to UTF-8.
+    ///
+    /// [`encoding`]: ../../index.html#encoding
     pub fn decoder(&self) -> Decoder {
         Decoder {
             #[cfg(feature = "encoding")]

src/utils.rs

@@ -90,9 +90,11 @@ where
 /// Wrapper around `Vec<u8>` that has a human-readable debug representation:
 /// printable ASCII symbols output as is, all other output in HEX notation.
 ///
-/// Also, when `serialize` feature is on, this type deserialized using
+/// Also, when [`serialize`] feature is on, this type deserialized using
 /// [`deserialize_byte_buf`](serde::Deserializer::deserialize_byte_buf) instead
 /// of vector's generic [`deserialize_seq`](serde::Deserializer::deserialize_seq)
+///
+/// [`serialize`]: ../index.html#serialize
 #[derive(PartialEq, Eq)]
 pub struct ByteBuf(pub Vec<u8>);
 
@@ -145,9 +147,11 @@ impl Serialize for ByteBuf {
 /// Wrapper around `&[u8]` that has a human-readable debug representation:
 /// printable ASCII symbols output as is, all other output in HEX notation.
 ///
-/// Also, when `serialize` feature is on, this type deserialized using
+/// Also, when [`serialize`] feature is on, this type deserialized using
 /// [`deserialize_bytes`](serde::Deserializer::deserialize_bytes) instead
 /// of vector's generic [`deserialize_seq`](serde::Deserializer::deserialize_seq)
+///
+/// [`serialize`]: ../index.html#serialize
 #[derive(PartialEq, Eq)]
 pub struct Bytes<'de>(pub &'de [u8]);