Improve documentation for `expand_empty_elements()` and `check_end_names()`
@@ -81,10 +81,26 @@ pub struct Reader<R: BufRead> {
check_end_names: bool,
/// check if comments contains `--` (false per default)
check_comments: bool,
- /// all currently Started elements which didn't have a matching
- /// End element yet
+ /// All currently Started elements which didn't have a matching
+ /// End element yet.
+ ///
+ /// For an XML
+ ///
+ /// ```xml
+ /// <root><one/><inner attr="value">|<tag></inner></root>
+ /// ```
+ /// when cursor at the `|` position buffer contains:
+ ///
+ /// ```text
+ /// rootinner
+ /// ^ ^
+ /// ```
+ ///
+ /// The `^` symbols shows which positions stored in the [`opened_starts`]
+ /// (0 and 4 in that case).
opened_buffer: Vec<u8>,
- /// opened name start indexes
+ /// Opened name start indexes into [`opened_buffer`]. See documentation
+ /// for that field for details
opened_starts: Vec<usize>,
/// a buffer to manage namespaces
ns_buffer: NamespaceBufferIndex,
@@ -122,9 +138,13 @@ impl<R: BufRead> Reader<R> {
/// Changes whether empty elements should be split into an `Open` and a `Close` event.
///
/// When set to `true`, all [`Empty`] events produced by a self-closing tag like `<tag/>` are
- /// expanded into a [`Start`] event followed by a [`End`] event. When set to `false` (the
+ /// expanded into a [`Start`] event followed by an [`End`] event. When set to `false` (the
/// default), those tags are represented by an [`Empty`] event instead.
///
+ /// Note, that setting this to `true` will lead to additional allocates that
+ /// needed to store tag name for an [`End`] event. There is no additional
+ /// allocation, however, if [`check_end_names()`] is also set.
+ ///
/// (`false` by default)
///
/// [`Empty`]: events/enum.Event.html#variant.Empty
@@ -187,6 +207,10 @@ impl<R: BufRead> Reader<R> {
/// Note that the emitted [`End`] event will not be modified if this is disabled, ie. it will
/// contain the data of the mismatched end tag.
///
+ /// Note, that setting this to `true` will lead to additional allocates that
+ /// needed to store tag name for an [`End`] event. There is no additional
+ /// allocation, however, if [`expand_empty_elements()`] is also set.
+ ///
/// (`true` by default)
///
/// [`End`]: events/enum.Event.html#variant.End
