Improve documentation

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "libloading"
-version = "0.5.2"
+version = "0.6.0"
 authors = ["Simonas Kazlauskas <libloading@kazlauskas.me>"]
 build = "build.rs"
 description = "A safer binding to platform’s dynamic library loading utilities"

src/changelog.rs

@@ -1,12 +1,26 @@
 //! Project changelog
 
-/// Release NEXT (2020-04-??)
+/// Release 0.6.0 (2020-04-0?)
 ///
-/// * Removed dependency on the C compiler to build this library on unix-like platforms. We used to
-///   utilize it to work-around the very unlikely possibility of the target having thread-unsafe
-///   `dlerror` function, but the effect of the work-around was very opportunistic. We deemed the
-///   cost of the work-around to be higher than the benefit of it.
-pub mod rNEXT {}
+/// * Introduced a new method [`os::unix::Library::get_singlethreaded`];
+/// * Added (untested) support for building when targetting Redox and Fuchsia;
+///
+/// ## Breaking changes
+///
+/// * Removed the dependency on the C compiler to build this library on UNIX-like platforms.
+///   `libloading` used to utilize a snippet written in C to work-around the unlikely possibility
+///   of the target having a thread-unsafe implementation of the `dlerror` function. The effect of
+///   the work-around was very opportunistic: it would not work if the function was called by
+///   forgoing `libloading`.
+///
+///   Starting with 0.6.0, [`Library::get`] on platforms where `dlerror` is not MT-safe (such as
+///   FreeBSD, DragonflyBSD or NetBSD) will unconditionally return an error when the underlying
+///   `dlsym` returns a null pointer. For the use-cases where loading null pointers is necessary
+///   consider using [`os::unix::Library::get_singlethreaded`] instead.
+///
+/// [`Library::get`]: crate::Library::get
+/// [`os::unix::Library::get_singlethreaded`]: crate::os::unix::Library::get_singlethreaded
+pub mod r0_6_0 {}
 
 
 /// Release 0.5.2 (2019-07-07)

src/lib.rs

@@ -137,10 +137,11 @@ impl Library {
     /// some sort of lazy initialization scheme, which makes loading TLS variables this way
     /// impossible. Using a TLS variable loaded this way on OS X is undefined behaviour.
     ///
-    /// On POSIX implementations where the `dlerror` function is not confirmed to be MT-safe, this
-    /// function will return an error if this function was to return `Ok` with a null `Symbol`
-    /// otherwise. As a work-around consider using the platform-specific
-    /// [`os::unix::Library::get_singlethreaded`] call.
+    /// On POSIX implementations where the `dlerror` function is not confirmed to be MT-safe (such
+    /// as FreeBSD), this function will unconditionally return an error the underlying `dlsym` call
+    /// returns a null pointer. There are rare situations where `dlsym` returns a genuine null
+    /// pointer without it being an error. If loading a null pointer is something you care about,
+    /// consider using the [`os::unix::Library::get_singlethreaded`] call.
     ///
     /// ## Examples
     ///

src/os/unix/mod.rs

@@ -189,14 +189,18 @@ impl Library {
     /// ensure that the loaded symbol is in fact a `T`. Using a value with a wrong type has no
     /// definied behaviour.
     ///
+    ///
+    ///
     /// ## Platform-specific behaviour
     ///
     /// OS X uses some sort of lazy initialization scheme, which makes loading TLS variables
     /// impossible. Using a TLS variable loaded this way on OS X is undefined behaviour.
     ///
-    /// On POSIX implementations where the `dlerror` function is not confirmed to be MT-safe, this
-    /// function will return an error if this function was to return `Ok` with a null `Symbol`
-    /// on other platforms. As a work-around consider using the [`Self::get_singlethreaded`] call.
+    /// On POSIX implementations where the `dlerror` function is not confirmed to be MT-safe (such
+    /// as FreeBSD), this function will unconditionally return an error the underlying `dlsym` call
+    /// returns a null pointer. There are rare situations where `dlsym` returns a genuine null
+    /// pointer without it being an error. If loading a null pointer is something you care about,
+    /// consider using the [`Library::get_singlethreaded`] call.
     #[inline(always)]
     pub unsafe fn get<T>(&self, symbol: &[u8]) -> ::Result<Symbol<T>> {
         #[cfg(mtsafe_dlerror)]

src/os/windows/mod.rs

@@ -68,8 +68,9 @@ impl Library {
     ///
     /// ## Unsafety
     ///
-    /// Pointer to a value of arbitrary type is returned. Using a value with wrong type is
-    /// undefined.
+    /// This function does not validate the type `T`. It is up to the user of this function to
+    /// ensure that the loaded symbol is in fact a `T`. Using a value with a wrong type has no
+    /// definied behaviour.
     pub unsafe fn get<T>(&self, symbol: &[u8]) -> ::Result<Symbol<T>> {
         ensure_compatible_types::<T, FARPROC>();
         let symbol = try!(cstr_cow_from_bytes(symbol));