Merge branch 'feature/improve-docs' into develop

Author: lo48576

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>);