increase documentation of statfs/statvfs to prevent confusion

Author: ultrabear

src/sys/statfs.rs

@@ -662,7 +662,7 @@ impl Debug for Statfs {
 
 /// Describes a mounted file system.
 ///
-/// The result is OS-dependent.  For a portable alternative, see
+/// The result is OS-dependent.  For a platform portable alternative, see
 /// [`statvfs`](crate::sys::statvfs::statvfs).
 ///
 /// # Arguments
@@ -680,7 +680,7 @@ pub fn statfs<P: ?Sized + NixPath>(path: &P) -> Result<Statfs> {
 
 /// Describes a mounted file system.
 ///
-/// The result is OS-dependent.  For a portable alternative, see
+/// The result is OS-dependent.  For a platform portable alternative, see
 /// [`fstatvfs`](crate::sys::statvfs::fstatvfs).
 ///
 /// # Arguments

src/sys/statvfs.rs

@@ -55,6 +55,10 @@ libc_bitflags!(
 
 /// Wrapper around the POSIX `statvfs` struct
 ///
+/// Note that the types provided by this struct are based off of libc definitions, and as such do
+/// not always resolve to the same concrete number type on different platforms. Using techniques 
+/// such as `u64::from` may be desirable when implementing "Rust portable" math.
+///
 /// For more information see the [`statvfs(3)` man pages](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/sys_statvfs.h.html).
 #[repr(transparent)]
 #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]