Add documentation

crlf0710 · crlf0710 · commit b7f4c299e3a8 · 2022-10-16T16:00:41.000+08:00
diff --git a/scripts/unicode.py b/scripts/unicode.py
@@ -190,70 +190,72 @@ def emit_general_category_module(f):
     f.write("""
 
     #[derive(Copy, Clone, Hash, Eq, PartialEq, Ord, PartialOrd, Debug)]
+    /// The most general classification of a character.
     pub enum GeneralCategory {
-        /// an uppercase letter
+        /// `Lu`, an uppercase letter
         LetterUppercase,
-        /// a lowercase letter
+        /// `Ll`, a lowercase letter
         LetterLowercase,
-        /// a digraphic character, with first part uppercase
+        /// `Lt`, a digraphic character, with first part uppercase
         LetterTitlecase,
-        /// a modifier letter
+        /// `Lm`, a modifier letter
         LetterModifier,
-        /// other letters, including syllables and ideographs
+        /// `Lo`, other letters, including syllables and ideographs
         LetterOther,
-        /// a nonspacing combining mark (zero advance width)
+        /// `Mn`, a nonspacing combining mark (zero advance width)
         MarkNonspacing,
-        /// a spacing combining mark (positive advance width)
+        /// `Mc`, a spacing combining mark (positive advance width)
         MarkSpacing,
-        /// an enclosing combining mark
+        /// `Me`, an enclosing combining mark
         MarkEnclosing,
-        /// a decimal digit
+        /// `Nd`, a decimal digit
         NumberDecimal,
-        /// a letterlike numeric character
+        /// `Nl`, a letterlike numeric character
         NumberLetter,
-        /// a numeric character of other type
+        /// `No`, a numeric character of other type
         NumberOther,
-        /// a connecting punctuation mark, like a tie
+        /// `Pc`, a connecting punctuation mark, like a tie
         PunctuationConnector,
-        /// a dash or hyphen punctuation mark
+        /// `Pd`, a dash or hyphen punctuation mark
         PunctuationDash,
-        /// an opening punctuation mark (of a pair)
+        /// `Ps`, an opening punctuation mark (of a pair)
         PunctuationOpen,
-        /// a closing punctuation mark (of a pair)
+        /// `Pe`, a closing punctuation mark (of a pair)
         PunctuationClose,
-        /// an initial quotation mark
+        /// `Pi`, an initial quotation mark
         PunctuationInitial,
-        /// a final quotation mark
+        /// `Pf`, a final quotation mark
         PunctuationFinal,
-        /// a punctuation mark of other type
+        /// `Po`, a punctuation mark of other type
         PunctuationOther,
-        /// a symbol of mathematical use
+        /// `Sm`, a symbol of mathematical use
         SymbolMath,
-        /// a currency sign
+        /// `Sc`, a currency sign
         SymbolCurrency,
-        /// a non-letterlike modifier symbol
+        /// `Sk`, a non-letterlike modifier symbol
         SymbolModifier,
-        /// a symbol of other type
+        /// `So`, a symbol of other type
         SymbolOther,
-        /// a space character (of various non-zero widths)
+        /// `Zs`, a space character (of various non-zero widths)
         SeparatorSpace,
-        /// U+2028 LINE SEPARATOR only
+        /// `Zl`, U+2028 LINE SEPARATOR only
         SeparatorLine,
-        /// U+2029 PARAGRAPH SEPARATOR only
+        /// `Zp`, U+2029 PARAGRAPH SEPARATOR only
         SeparatorParagraph,
-        /// a C0 or C1 control code
+        /// `Cc`, a C0 or C1 control code
         OtherControl,
-        /// a format control character
+        /// `Cf`, a format control character
         OtherFormat,
-        /// a surrogate code point
+        /// `Cs`, a surrogate code point
         OtherSurrogate,
-        /// a private-use character
+        /// `Co`, a private-use character
         OtherPrivateUse,
-        /// a reserved unassigned code point or a noncharacter
+        /// `Cn`, a reserved unassigned code point or a noncharacter
         OtherUnassigned,
     }
 
     #[derive(Copy, Clone, Hash, Eq, PartialEq, Ord, PartialOrd, Debug)]
+    /// Groupings of the most general classification of a character.
     pub enum GeneralCategoryGroup {
         /// Lu | Ll | Lt | Lm | Lo
         Letter,
@@ -379,15 +381,25 @@ def emit_emoji_module(f):
 
     #[derive(Copy, Clone, Hash, Eq, PartialEq, Ord, PartialOrd, Debug)]
     #[non_exhaustive]
+    /// The emoji character properties of a character.
     pub enum EmojiStatus {
+        /// `Emoji=NO`, `Emoji_Component=NO`
         NonEmoji,
+        /// `Emoji=NO`, `Emoji_Component=YES`
         NonEmojiButEmojiComponent,
+        /// `Emoji=YES`, `Emoji_Component=NO`;`Emoji_Presentation=YES`
         EmojiPresentation,
+        /// `Emoji=YES`, `Emoji_Component=NO`;`Emoji_Modifier_Base=YES`
         EmojiModifierBase,
+        /// `Emoji=YES`, `Emoji_Component=NO`;`Emoji_Presentation=YES`, `Emoji_Modifier_Base=YES`
         EmojiPresentationAndModifierBase,
+        /// `Emoji=YES`, `Emoji_Component=NO`
         EmojiOther,
+        /// `Emoji=YES`, `Emoji_Component=YES`;`Emoji_Presentation=YES`
         EmojiPresentationAndEmojiComponent,
+        /// `Emoji=YES`, `Emoji_Component=YES`;`Emoji_Presentation=YES`, `Emoji_Modifier=YES`
         EmojiPresentationAndModifierAndEmojiComponent,
+        /// `Emoji=YES`, `Emoji_Component=YES`
         EmojiOtherAndEmojiComponent,
     }
     #[inline]
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,21 +1,70 @@
+// Copyright 2012-2015 The Rust Project Developers. See the COPYRIGHT
+// file at the top-level directory of this distribution and at
+// http://rust-lang.org/COPYRIGHT.
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+
+//! Query character Unicode properties according to
+//! [Unicode Standard Annex #44](https://www.unicode.org/reports/tr44/)
+//! and [Unicode Technical Standard #51](https://www.unicode.org/reports/tr51/)
+//! rules.
+//!
+//! ```rust
+//! use unicode_properties::UnicodeEmoji;
+//! use unicode_properties::UnicodeGeneralCategory;
+//!
+//! fn main() {
+//!     let ch = '🦀'; // U+1F980 CRAB
+//!     let is_emoji = ch.is_emoji_char();
+//!     let group = ch.general_category_group();
+//!     println!("{}({:?})", ch, group);
+//!     println!("The above char {} for use as emoji char.",
+//!              if is_emoji { "is recommended" } else { "is not recommended" });
+//! }
+//! ```
+//!
+//! # Features
+//!
+//! ## `general-category`
+//!
+//! Provides the most general classification of a character,
+//! based on its primary characteristic.
+//!
+//! ## `emoji`
+//!
+//! Provides the emoji character properties of a character.
+//!
+#![deny(missing_docs)]
+
 #[rustfmt::skip]
 mod tables;
 
 #[cfg(feature = "emoji")]
+/// Query the emoji character properties of a character.
 pub mod emoji {
     pub use crate::tables::emoji::EmojiStatus;
 
+    /// Query the emoji character properties of a character.
     pub trait UnicodeEmoji: Sized {
+        /// Returns the emoji character properties in a status enum.
         fn emoji_status(self) -> EmojiStatus;
 
+        /// Checks whether this character is recommended for use as emoji, i.e. `Emoji=YES`.
         fn is_emoji_char(self) -> bool {
             crate::tables::emoji::is_emoji_status_for_emoji_char(self.emoji_status())
         }
 
+        /// Checks whether this character are used in emoji sequences where they're not
+        /// intended for independent, direct input, i.e. `Emoji_Component=YES`.
         fn is_emoji_component(self) -> bool {
             crate::tables::emoji::is_emoji_status_for_emoji_component(self.emoji_status())
         }
 
+        /// Checks whether this character occurs in emoji sequences, i.e. `Emoji=YES | Emoji_Component=YES`
         fn is_emoji_char_or_emoji_component(self) -> bool {
             crate::tables::emoji::is_emoji_status_for_emoji_char_or_emoji_component(
                 self.emoji_status(),
@@ -30,42 +79,66 @@ pub mod emoji {
     }
 
     #[inline]
+    /// Checks whether this character is the U+200D ZERO WIDTH JOINER (ZWJ) character.
+    ///
+    /// It can be used between the elements of a sequence of characters to indicate that
+    /// a single glyph should be presented if available.
     pub fn is_zwj(c: char) -> bool {
         c == '\u{200D}'
     }
 
     #[inline]
+    /// Checks whether this character is the U+FE0F VARIATION SELECTOR-16 (VS16) character, used to
+    /// request an emoji presentation for an emoji character.
     pub fn is_emoji_presentation_selector(c: char) -> bool {
         c == '\u{FE0F}'
     }
 
     #[inline]
+    /// Checks whether this character is the U+FE0E VARIATION SELECTOR-15 (VS15) character, used to
+    /// request a text presentation for an emoji character.
     pub fn is_text_presentation_selector(c: char) -> bool {
         c == '\u{FE0E}'
     }
 
     #[inline]
+    /// Checks whether this character is one of the Regional Indicator characters.
+    ///
+    /// A pair of REGIONAL INDICATOR symbols is referred to as an emoji_flag_sequence.
     pub fn is_regional_indicator(c: char) -> bool {
         matches!(c, '\u{1F1E6}'..='\u{1F1FF}')
     }
 
     #[inline]
+    /// Checks whether this character is one of the Tag Characters.
+    ///
+    /// These can be used in indicating variants or extensions of emoji characters.
     pub fn is_tag_character(c: char) -> bool {
         matches!(c, '\u{E0020}'..='\u{E007F}')
     }
 }
 
 #[cfg(feature = "general-category")]
+/// Query the general category property of a character.
 pub mod general_category {
     pub use crate::tables::general_category::{GeneralCategory, GeneralCategoryGroup};
 
+    /// Query the general category property of a character.
+    ///
+    /// See [General Category Values](https://www.unicode.org/reports/tr44/#General_Category_Values) for more info.
     pub trait UnicodeGeneralCategory: Sized {
+        /// Queries the most general classification of a character.
         fn general_category(self) -> GeneralCategory;
 
+        /// Queries the grouping of the most general classification of a character.
         fn general_category_group(self) -> GeneralCategoryGroup {
             crate::tables::general_category::general_category_group(self.general_category())
         }
 
+        /// Queries whether the most general classification of a character belongs to the `LetterCased` group
+        ///
+        /// The `LetterCased` group includes `LetterUppercase`, `LetterLowercase`, and `LetterTitlecase`
+        /// categories, and is a subset of the `Letter` group.
         fn is_letter_cased(self) -> bool {
             crate::tables::general_category::general_category_is_letter_cased(
                 self.general_category(),
@@ -83,16 +156,21 @@ pub mod general_category {
 pub use tables::UNICODE_VERSION;
 
 #[cfg(feature = "emoji")]
+#[doc(inline)]
 pub use emoji::UnicodeEmoji;
 
 #[cfg(feature = "emoji")]
+#[doc(inline)]
 pub use emoji::EmojiStatus;
 
 #[cfg(feature = "general-category")]
+#[doc(inline)]
 pub use general_category::GeneralCategory;
 
 #[cfg(feature = "general-category")]
+#[doc(inline)]
 pub use general_category::GeneralCategoryGroup;
 
 #[cfg(feature = "general-category")]
+#[doc(inline)]
 pub use general_category::UnicodeGeneralCategory;
diff --git a/src/tables.rs b/src/tables.rs
