Add missing Language docs + doc tests. (#233)

Author: waywardmonkeys

harfbuzz/src/buffer.rs

@@ -198,7 +198,7 @@ impl Buffer {
     ///
     /// Finally, if buffer language is not set (ie. is `HB_LANGUAGE_INVALID`),
     /// it will be set to the process's default language as returned by
-    /// `hb_language_get_default()`. This may change in the future by
+    /// [`Language::get_process_default()`]. This may change in the future by
     /// taking buffer script into consideration when choosing a language.
     ///
     /// ```

harfbuzz/src/language.rs

@@ -7,10 +7,17 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-#![allow(missing_docs)]
-
 use crate::sys;
 
+/// A language tag.
+///
+/// This corresponds to a [BCP 47] language tag.
+///
+/// This is a wrapper around the [`hb_language_t`] type from the
+/// [`harfbuzz-sys`](crate::sys) crate.
+///
+/// [`hb_language_t`]: crate::sys::hb_language_t
+/// [BCP 47]: https://tools.ietf.org/html/bcp47
 #[derive(Copy, Clone, PartialEq, PartialOrd)]
 pub struct Language {
     /// The underlying `hb_language_t` from the `harfbuzz-sys` crate.
@@ -22,6 +29,26 @@ pub struct Language {
 }
 
 impl Language {
+    /// Construct a `Language` from a string.
+    ///
+    /// The string should be a [BCP 47] language tag.
+    ///
+    /// Example:
+    ///
+    /// ```
+    /// let lang = harfbuzz::Language::from_string("en-US");
+    /// assert!(lang.is_valid());
+    /// let lang = harfbuzz::Language::from_string("ja");
+    /// assert!(lang.is_valid());
+    /// let lang = harfbuzz::Language::from_string("zh-Hant");
+    /// assert!(lang.is_valid());
+    /// let lang = harfbuzz::Language::from_string("sr-Latn-RS");
+    /// assert!(lang.is_valid());
+    /// let lang = harfbuzz::Language::from_string("");
+    /// assert!(!lang.is_valid());
+    /// ```
+    ///
+    /// [BCP 47]: https://tools.ietf.org/html/bcp47
     pub fn from_string(lang: &str) -> Self {
         Language {
             raw: unsafe {
@@ -33,6 +60,13 @@ impl Language {
         }
     }
 
+    /// Converts the language to a string.
+    ///
+    /// Example:
+    /// ```
+    /// let lang = harfbuzz::Language::from_string("en-US");
+    /// assert_eq!(lang.to_string(), "en-us");
+    /// ```
     pub fn to_string(&self) -> &str {
         unsafe { std::ffi::CStr::from_ptr(sys::hb_language_to_string(self.raw)) }
             .to_str()
@@ -48,16 +82,36 @@ impl Language {
         Language { raw }
     }
 
+    /// Convert the `Language` to a raw pointer.
+    ///
+    /// This is useful for interfacing with functions from the
+    /// [`harfbuzz-sys`](crate::sys) crate that haven't been safely exposed.
     pub fn as_raw(self) -> sys::hb_language_t {
         self.raw
     }
 
+    /// Returns the default language for the process locale.
+    ///
+    /// See [`hb_language_get_default()`] for more information.
+    ///
+    /// Example:
+    ///
+    /// ```
+    /// let lang = harfbuzz::Language::get_process_default();
+    /// assert!(lang.is_valid());
+    /// ```
+    ///
+    /// [`hb_language_get_default()`]: https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-language-get-default
     pub fn get_process_default() -> Self {
         Language {
             raw: unsafe { sys::hb_language_get_default() },
         }
     }
 
+    /// Returns whether or not the language is valid.
+    ///
+    /// TODO: This should go away and the constructor should
+    /// return an `Option<Language>`.
     pub fn is_valid(self) -> bool {
         !self.raw.is_null()
     }