Nicer doc formatting

README.md

@@ -53,7 +53,7 @@ xml-rs uses [Cargo](https://crates.io), so add it with `cargo add xml` or modify
 
 ```toml
 [dependencies]
-xml = "0.8"
+xml = "0.8.16"
 ```
 
 The package exposes a single crate called `xml`.
@@ -129,6 +129,13 @@ small program (BTW, it is built with `cargo build` and can be run after that) wh
 statistics about specified XML document. It can also be used to check for well-formedness of
 XML documents - if a document is not well-formed, this program will exit with an error.
 
+
+## Parsing untrusted inputs
+
+The parser is written in safe Rust subset, so by Rust's guarantees the worst that it can do is to cause a panic.
+You can use `ParserConfig` to set limits on maximum lenghts of names, attributes, text, entities, etc.
+You should also set a maximum document size via `io::Read`'s [`take(max)`](https://doc.rust-lang.org/stable/std/io/trait.Read.html#method.take) method.
+
 Writing XML documents
 ---------------------
 

src/macros.rs

@@ -3,47 +3,41 @@
 //! Contains several macros used in this crate.
 
 macro_rules! gen_setter {
- ($(#[$comments:meta])* $target:ty, $field:ident : into $t:ty) => {
- impl $target {
+ ($(#[$comments:meta])* $field:ident : into $t:ty) => {
+
  $(#[$comments])*
  ///
- /// See [`ParserConfig`][crate::ParserConfig] fields docs for details
+ /// <small>See [`ParserConfig`][crate::ParserConfig] fields docs for details</small>
  #[inline]
- pub fn $field<T: Into<$t>>(mut self, value: T) -> $target {
+ pub fn $field<T: Into<$t>>(mut self, value: T) -> Self {
  self.$field = value.into();
  self
  }
- }
  };
- ($(#[$comments:meta])* $target:ty, $field:ident : val $t:ty) => {
- impl $target {
+ ($(#[$comments:meta])* $field:ident : val $t:ty) => {
  $(#[$comments])*
  ///
- /// See [`ParserConfig`][crate::ParserConfig] fields docs for details
+ /// <small>See [`ParserConfig`][crate::ParserConfig] fields docs for details</small>
  #[inline]
- pub fn $field(mut self, value: $t) -> $target {
+ pub fn $field(mut self, value: $t) -> Self {
  self.$field = value;
  self
  }
- }
  };
- ($(#[$comments:meta])* $target:ty, $field:ident : delegate $t:ty) => {
- impl $target {
+ ($(#[$comments:meta])* $field:ident : delegate $t:ty) => {
  $(#[$comments])*
  ///
- /// See [`ParserConfig`][crate::ParserConfig] fields docs for details
+ /// <small>See [`ParserConfig`][crate::ParserConfig] fields docs for details</small>
  #[inline]
- pub fn $field(mut self, value: $t) -> $target {
+ pub fn $field(mut self, value: $t) -> Self {
  self.c.$field = value;
  self
  }
- }
  };
- ($(#[$comments:meta])* $target:ty, $field:ident : c2 $t:ty) => {
- impl $target {
+ ($(#[$comments:meta])* $field:ident : c2 $t:ty) => {
  $(#[$comments])*
  ///
- /// See [`ParserConfig2`][crate::reader::ParserConfig] fields docs for details
+ /// <small>See [`ParserConfig2`][crate::reader::ParserConfig2] fields docs for details</small>
  #[inline]
  #[must_use]
  pub fn $field(self, value: $t) -> ParserConfig2 {
@@ -53,12 +47,14 @@ macro_rules! gen_setter {
  }
  .$field(value)
  }
- }
  };
 }
 
 macro_rules! gen_setters {
- ($target:ty, $($(#[$comments:meta])* $field:ident : $k:tt $tpe:ty),+) => ($(
- gen_setter! { $(#[$comments])* $target, $field : $k $tpe }
- )+)
+ ($target:ident, $($(#[$comments:meta])* $field:ident : $k:tt $tpe:ty),+) => (
+ impl $target {$(
+
+ gen_setter! { $(#[$comments])* $field : $k $tpe }
+ )+
+ })
 }

src/reader/config.rs

@@ -9,7 +9,7 @@ use crate::util::Encoding;
 const DEFAULT_MAX_ENTITY_EXPANSION_LENGTH: usize = 1_000_000;
 const DEFAULT_MAX_ENTITY_EXPANSION_DEPTH: u8 = 10;
 
-/// Parser configuration structure.
+/// Parser configuration structure. **There are more config methods than public fileds — see methods below**.
 ///
 /// This structure contains various configuration options which affect
 /// behavior of the parser.
@@ -92,6 +92,8 @@ pub struct ParserConfig {
  ///
  /// By default any whitespace that is not enclosed within at least one level of elements will be
  /// ignored. Setting this value to false will cause root level whitespace events to be emitted.
+ ///
+ /// **There are configuration options – see methods below**
  pub ignore_root_level_whitespace: bool,
 }