Document utilities

great_ai/utilities/language/__init__.py

@@ -1,3 +0,0 @@
-from .english_name_of_language import english_name_of_language
-from .is_english import is_english
-from .predict_language import predict_language

great_ai/utilities/language/english_name_of_language.py

@@ -4,6 +4,26 @@ from langcodes import Language
 
 
 def english_name_of_language(language_code: Optional[str]) -> str:
+    """Human-friendly English name of language from its `language_code`.
+
+    A thin wrapper over [langcodes](https://github.com/rspeer/langcodes) for convenient
+    language tagging.
+
+    Examples:
+        >>> english_name_of_language('en-US')
+        'English (United States)'
+
+        >>> english_name_of_language('und')
+        'Unknown language'
+
+    Args:
+        language_code: Language code, for example, returned by
+            [great_ai.utilities.predict_language][].
+
+    Returns:
+        English name of language.
+    """
+
     if not language_code:
         language_code = "und"
 

great_ai/utilities/language/is_english.py

@@ -4,6 +4,28 @@ from langcodes import standardize_tag, tag_distance
 
 
 def is_english(language_code: Optional[str]) -> bool:
+    """Decide whether the `language_code` is of an English language.
+
+    A thin wrapper over [langcodes](https://github.com/rspeer/langcodes) for convenient
+    language tagging.
+
+    Examples:
+        >>> is_english('en-US')
+        True
+
+        >>> is_english(None)
+        False
+
+        >>> is_english('und')
+        False
+
+    Args:
+        language_code: Language code, for example, returned by
+            `[great_ai.utilities.predict_language][].
+
+    Returns:
+        Boolean indicating whether it's English.
+    """
     if not language_code:
         language_code = "und"
 

great_ai/utilities/language/predict_language.py

@@ -5,6 +5,23 @@ from langdetect import LangDetectException, detect
 
 
 def predict_language(text: Optional[str]) -> str:
+    """Predict the language code from text.
+
+    A thin wrapper over [langcodes](https://github.com/rspeer/langcodes) for convenient
+    language tagging.
+
+    Examples:
+        >>> predict_language('This is a sentence.')
+        'en'
+
+    Args:
+        text: Text used for prediction.
+
+    Returns:
+        The predicted language code (en, en-US) or `und` if a prediction could not be
+            made.
+    """
+
     if not text:
         return Language.make().to_tag()