Merge branch 'feature/improve-docs' into develop

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## [Unreleased]
 
+* Documents are improved a little.
+
 ## [0.4.3]
 
 * Longer lifetime for iterator returned by

src/low/v7400/attribute/value.rs

@@ -13,7 +13,9 @@ use crate::low::v7400::AttributeType;
 /// * `get_*_or_type()` returns `Result<_, AttributeType>`.
 ///     + If a value of the expected type available, returns `Ok(_)`.
 ///     + If not, returns `Ok(ty)` where `ty` is value type (same value as
-///       returned by `type_()`.
+///       returned by [`type_()`][`type_`].
+///
+/// [`type_`]: #method.type_
 #[derive(Debug, Clone, PartialEq)]
 pub enum AttributeValue {
     /// Single `bool`.

src/pull_parser.rs

@@ -7,7 +7,7 @@
 //! These modules are common among all supported FBX versions:
 //!
 //! * Error types (defined in [`error`] module).
-//! * `AnyParser` feature (defined in [`any`] module).
+//! * [`AnyParser`] feature (defined in [`any`] module).
 //! * Parser source traits and wrappers (defined in [`reader`] module).
 //!
 //! # Using pull parser
@@ -85,6 +85,7 @@
 //! [`any`]: any/index.html
 //! [`error`]: error/index.html
 //! [`reader`]: reader/index.html
+//! [`AnyParser`]: any/enum.AnyParser.html
 
 pub use self::{
     error::{Error, Result, Warning},

src/pull_parser/any.rs

@@ -50,8 +50,12 @@ fn parser_version(header: FbxHeader) -> Result<ParserVersion> {
 
 /// Loads a tree from the given reader.
 ///
-/// This works for seekable readers (which implement `std::io::Seek`), but
-/// `from_seekable_reader` should be used for them, because it is more efficent.
+/// This works for seekable readers (which implement [`std::io::Seek`]), but
+/// [`from_seekable_reader`] should be used for them, because it is more
+/// efficent.
+///
+/// [`std::io::Seek`]: https://doc.rust-lang.org/stable/std/io/trait.Seek.html
+/// [`from_seekable_reader`]: fn.from_seekable_reader.html
 pub fn from_reader<R: Read>(mut reader: R) -> Result<AnyParser<PlainSource<R>>> {
     let header = FbxHeader::load(&mut reader)?;
     match parser_version(header)? {

src/pull_parser/error.rs

@@ -47,7 +47,7 @@ impl Error {
         self.repr.position.as_ref()
     }
 
-    /// Creates a new `error` with the given syntactic position info.
+    /// Creates a new `Error` with the given syntactic position info.
     pub(crate) fn with_position(error: ErrorContainer, position: SyntacticPosition) -> Self {
         Self {
             repr: Box::new(Repr::with_position(error, position)),
@@ -117,18 +117,27 @@ pub enum ErrorKind {
     /// Invalid data.
     ///
     /// With this error kind, the inner error must be [`DataError`].
+    ///
+    /// [`DataError`]: enum.DataError.html
     Data,
     /// I/O error.
     ///
     /// With this error kind, the inner error must be [`std::io::Error`].
+    ///
+    /// [`std::io::Error`]:
+    /// https://doc.rust-lang.org/stable/std/io/struct.Error.html
     Io,
     /// Invalid operation.
     ///
     /// With this error kind, the inner error must be [`OperationError`].
+    ///
+    /// [`OperationError`]: enum.OperationError.html
     Operation,
     /// Critical warning.
     ///
     /// With this error kind, the inner error must be [`Warning`].
+    ///
+    /// [`Warning`]: enum.Warning.html
     Warning,
 }
 

src/pull_parser/reader.rs

@@ -34,18 +34,19 @@ pub trait ParserSource: Sized + io::Read {
     /// This is called many times during parsing, so it is desirable to be fast
     /// as possible.
     ///
-    /// Reader types with `std::io::Seek` can implement this as
+    /// Reader types with [`std::io::Seek`] can implement this as
     /// `self.seek(SeekFrom::Current(0)).unwrap()`, but this is fallible and
     /// can be inefficient.
     /// Use of [`PositionCacheReader`] is reccomended.
     ///
+    /// [`std::io::Seek`]: https://doc.rust-lang.org/stable/std/io/trait.Seek.html
     /// [`PositionCacheReader`]: struct.PositionCacheReader.html
     fn position(&self) -> u64;
 
     /// Skips (seeks formward) the given size.
     ///
-    /// Reader types can make this more efficient using `io::Seek::seek` if
-    /// possible.
+    /// Reader types can make this more efficient using [`std::io::Seek::seek`]
+    /// if possible.
     ///
     /// # Examples
     ///
@@ -61,6 +62,9 @@ pub trait ParserSource: Sized + io::Read {
     /// reader.skip_distance(7).expect("Failed to skip");
     /// assert_eq!(reader.position(), 7);
     /// ```
+    ///
+    /// [`std::io::Seek::seek`]:
+    /// https://doc.rust-lang.org/stable/std/io/trait.Seek.html#tymethod.seek
     fn skip_distance(&mut self, distance: u64) -> io::Result<()> {
         // NOTE: `let mut limited = self.by_ref().take(distance);` is E0507.
         let mut limited = io::Read::take(self.by_ref(), distance);
@@ -70,8 +74,8 @@ pub trait ParserSource: Sized + io::Read {
 
     /// Skips (seeks forward) to the given position.
     ///
-    /// Reader types can make this more efficient using `io::Seek::seek` if
-    /// possible.
+    /// Reader types can make this more efficient using [`std::io::Seek::seek`]
+    /// if possible.
     ///
     /// # Panics
     ///
@@ -91,6 +95,9 @@ pub trait ParserSource: Sized + io::Read {
     /// reader.skip_to(7).expect("Failed to skip");
     /// assert_eq!(reader.position(), 7);
     /// ```
+    ///
+    /// [`std::io::Seek::seek`]:
+    /// https://doc.rust-lang.org/stable/std/io/trait.Seek.html#tymethod.seek
     fn skip_to(&mut self, pos: u64) -> io::Result<()> {
         let distance = pos
             .checked_sub(self.position())

src/pull_parser/reader/position_cache.rs

@@ -20,12 +20,12 @@ pub struct PositionCacheReader<R> {
 }
 
 impl<R: io::Read> PositionCacheReader<R> {
-    /// Creates a new `PositionCache`.
+    /// Creates a new `PositionCacheReader`.
     pub fn new(inner: R) -> Self {
         Self { inner, position: 0 }
     }
 
-    /// Creates a new `PositionCache` with the given offset.
+    /// Creates a new `PositionCacheReader` with the given offset.
     ///
     /// # Examples
     ///
@@ -62,7 +62,7 @@ impl<R: io::Read> PositionCacheReader<R> {
     ///
     /// A seek beyond the end of a stream is allowed, but behavior is defined by
     /// the implementation.
-    /// See the document for `std::io::Seek::seek()`.
+    /// See the document for [`std::io::Seek::seek()`][`std::io::Seek::seek`].
     ///
     /// # Examples
     ///
@@ -79,6 +79,9 @@ impl<R: io::Read> PositionCacheReader<R> {
     /// reader.skip_distance(7).expect("Failed to skip");
     /// assert_eq!(reader.position(), 7);
     /// ```
+    ///
+    /// [`std::io::Seek::seek`]:
+    /// https://doc.rust-lang.org/stable/std/io/trait.Seek.html#tymethod.seek
     pub fn skip_distance(&mut self, mut distance: u64) -> io::Result<()>
     where
         R: io::Seek,

src/pull_parser/reader/source.rs

@@ -8,11 +8,12 @@ use crate::pull_parser::{reader::PositionCacheReader, ParserSource};
 ///
 /// This may be inefficient, but works with any reader types.
 /// It is recommended to use [`SeekableSource`] if the reader implements
-/// `std::io::Seek`.
+/// [`std::io::Seek`].
 ///
 /// This internally uses `PositionCacheReader`, so users don't need to wrap
 /// readers by `PositionCacheReader` manually.
 ///
+/// [`std::io::Seek`]: https://doc.rust-lang.org/stable/std/io/trait.Seek.html
 /// [`PositionCacheReader`]: struct.PositionCacheReader.html
 /// [`SeekableSource`]: struct.SeekableSource.html
 #[derive(Debug, Clone, Copy)]

src/pull_parser/v7400/attribute.rs

@@ -14,7 +14,9 @@ use crate::{
 use self::array::{ArrayAttributeValues, AttributeStreamDecoder, BooleanArrayAttributeValues};
 pub use self::loader::LoadAttribute;
 
-/// Use `low::v7400::AttributeValue` instead.
+/// Use [`low::v7400::AttributeValue`] instead.
+///
+/// [`low::v7400::AttributeValue`]: ../../../low/v7400/enum.AttributeValue.html
 #[deprecated(
     since = "0.4.0",
     note = "`DirectAttributeValue` is moved to `low::v7400::AttributeValue`"

src/pull_parser/v7400/attribute/loaders/single.rs

@@ -6,7 +6,7 @@ use crate::pull_parser::{v7400::LoadAttribute, Result};
 
 /// Loader for primitive types.
 ///
-/// Supported types are: [`bool`], [`i16`] , [`i32`], [`i64`], [`f32`], [`f64`].
+/// Supported types are: `bool`, `i16` , `i32`, `i64`, `f32`, and `f64`.
 #[derive(Default, Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct PrimitiveLoader<T>(std::marker::PhantomData<T>);
 

src/pull_parser/v7400/parser.rs

@@ -20,9 +20,11 @@ use crate::{
 /// Warning handler type.
 type WarningHandler = Box<dyn FnMut(Warning, &SyntacticPosition) -> Result<()>>;
 
-/// Creates a new `Parser` from the given reader.
+/// Creates a new [`Parser`] from the given reader.
 ///
 /// Returns an error if the given FBX version in unsupported.
+///
+/// [`Parser`]: struct.Parser.html
 pub fn from_reader<R>(header: FbxHeader, reader: R) -> Result<Parser<PlainSource<R>>>
 where
     R: io::Read,
@@ -33,9 +35,11 @@ where
     )
 }
 
-/// Creates a new `Parser` from the given seekable reader.
+/// Creates a new [`Parser`] from the given seekable reader.
 ///
 /// Returns an error if the given FBX version in unsupported.
+///
+/// [`Parser`]: struct.Parser.html
 pub fn from_seekable_reader<R>(header: FbxHeader, reader: R) -> Result<Parser<SeekableSource<R>>>
 where
     R: io::Read + io::Seek,
@@ -175,6 +179,9 @@ impl<R: ParserSource> Parser<R> {
     /// already failed and returned error.
     /// If you call `next_event()` with failed parser, error created from
     /// [`OperationError::AlreadyAborted`] will be returned.
+    ///
+    /// [`OperationError::AlreadyAborted`]:
+    /// ../error/enum.OperationError.html#variant.AlreadyAborted
     pub fn next_event(&mut self) -> Result<Event<'_, R>> {
         let previous_depth = self.current_depth();
 
@@ -386,19 +393,22 @@ impl<R: ParserSource> Parser<R> {
 
     /// Ignore events until the current node closes.
     ///
-    /// In other words, this discards parser events including `EndNode` for the
-    /// current node.
+    /// This discards parser events until the [`EndNode`] event for the current
+    /// node is read.
+    /// The last [`EndNode`] (for the current node) is also discarded.
     ///
-    /// This method seeks to the already known node end position, without
-    /// parsing events to be ignored.
-    /// Because of this, some errors can be overlooked, or some errors can be
-    /// detected at the different position from the true error position.
+    /// This method seeks to the node end position without any additional
+    /// parsing, since the parser already knows the node end position.
+    /// Because of this, some errors can be overlooked, or detected at the
+    /// different position from the true error position.
     ///
     /// To detect errors correctly, you should use [`next_event`] manually.
+    /// See an example to how to do this.
     ///
     /// # Panics
     ///
-    /// Panics if there are no open nodes.
+    /// Panics if there are no open nodes, i.e. when [`current_depth()`][`current_depth`]
+    /// returns 0.
     ///
     /// # Examples
     ///
@@ -414,6 +424,26 @@ impl<R: ParserSource> Parser<R> {
     /// parser.skip_current_node().expect("Failed to skip current node");
     /// assert_eq!(parser.current_depth(), depth - 1);
     /// ```
+    ///
+    /// `parser.skip_current_node()` is almost same as the code below, except
+    /// for error handling.
+    ///
+    /// ```no_run
+    /// # use fbxcel::pull_parser::{v7400::{Parser, Event}, ParserSource, Result};
+    /// fn skip_current_node<R: ParserSource>(parser: &mut Parser<R>) -> Result<()> {
+    ///     loop {
+    ///         match parser.next_event()? {
+    ///             Event::StartNode(_) => skip_current_node(parser)?,
+    ///             Event::EndNode => return Ok(()),
+    ///             Event::EndFbx(_) => panic!("Attempt to skip implicit top-level node"),
+    ///         }
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// [`next_event`]: #method.next_event
+    /// [`current_depth`]: #method.current_depth
+    /// [`EndNode`]: enum.Event.html#variant.EndNode
     pub fn skip_current_node(&mut self) -> Result<()> {
         let end_pos = self
             .state