better lib structure/docs

src/entity.rs

@@ -6,43 +6,72 @@ use serde::{Deserialize, Serialize};
 /// A Wikibase entity: this could be an entity, property, or lexeme.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct Entity {
+    /// All of the claims on the entity.
     pub claims: Vec<(Pid, ClaimValue)>,
+    /// The type of the entity.
     pub entity_type: EntityType,
-    pub description: Text,
+    /// All of the descriptions in all known languages.
+    pub description: Vec<Text>,
+    /// All of the labels in all known languages.
+    pub labels: Vec<Text>,
 }
 
+/// The type of entity: normal entity with a Qid, a property with a Pid, or a lexeme with a Lid.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
+#[non_exhaustive]
 pub enum EntityType {
+    /// An entity with a Qid.
     Entity,
+    /// An entity with a Pid.
     Property,
+    /// An entity with a Lid.
     Lexeme,
 }
 
 /// Data relating to a claim value.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub enum ClaimValueData {
+    /// The ID of a file on Wikimedia Commons.
     CommonsMedia(String),
+    /// Coordinates on some globe.
     GlobeCoordinate {
-        //supported
+        /// Latitude.
         lat: f64,
+        /// Longitude.
         lon: f64,
+        /// How many degrees of distance of precision there are.
         precision: f64,
+        /// The globe the coordnaties are on, usually usually Q2 for Earth.
         globe: Qid,
     },
+    /// A Wikidata item.
     Item(Qid),
+    /// A Wikidata property.
     Property(Pid),
+    /// A language-less string of text.
     Stringg(String),
+    /// Text with a language.
     MonolingualText(Text),
+    /// The same text, translated across multiple languages.
     MultilingualText(Vec<Text>),
+    /// An external identifier.
     ExternalID(String),
+    /// Some numeric quantity of something.
     Quantity {
+        /// How much.
         amount: f64, // technically it could exceed the bound, but meh
+        /// The lowest possible value. If this isn't present then it is exactly the amount.
         lower_bound: Option<f64>,
+        /// The highest possible value. If this isn't present then it is exactly the amount.
         upper_bound: Option<f64>,
+        /// The units used.
         unit: Option<Qid>, // *could* be any IRI but in practice almost all are Wikidata entity IRIs
     },
+    /// A point in time time.
     DateTime {
+        /// The time as a Chrono DateTime.
         date_time: DateTime<chrono::offset::Utc>,
+        /// The precision of the date:
         /// 0 - billion years
         /// 1 - 100 million years
         /// 2 - 10 million years
@@ -60,15 +89,25 @@ pub enum ClaimValueData {
         /// 14 - second (deprecated)
         precision: u8,
     },
+    /// A URL.
     Url(String),
+    /// A LaTeX math expression.
     MathExpr(String),
+    /// A geometric shape. The value of the string is currently unspecified.
     GeoShape(String),
+    /// LilyPond musical notation.
     MusicNotation(String),
+    /// ID of a file with tabular data on Wikimedia commons.
     TabularData(String),
+    /// A lexeme ID on Wikidata.
     Lexeme(Lid),
+    /// A form ID on Wikidata.
     Form(Fid),
+    /// A sense ID on Wikidata.
     Sense(Sid),
+    /// No value.
     NoValue,
+    /// Unknown value.
     UnknownValue,
 }
 
@@ -95,20 +134,24 @@ impl Default for Rank {
 /// A group of claims that make up a single reference.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ReferenceGroup {
+    /// All of the claims.
     pub claims: Vec<(Pid, ClaimValueData)>,
 }
 
 /// A claim value.
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
 pub struct ClaimValue {
+    /// The data of the claim.
     pub data: ClaimValueData,
     pub rank: Rank,
+    /// The globally unique claim ID.
     pub id: String,
     pub qualifiers: Vec<(Pid, ClaimValueData)>,
     pub references: Vec<ReferenceGroup>,
 }
 
 impl Entity {
+    /// All of the values of "instance of" on the entity.
     pub fn instances(&self) -> Vec<Qid> {
         let mut instances = Vec::with_capacity(1);
         for (pid, claim) in &self.claims {
@@ -122,6 +165,7 @@ impl Entity {
         instances
     }
 
+    /// When the entity started existing.
     pub fn start_time(&self) -> Option<DateTime<chrono::offset::Utc>> {
         for (pid, claim) in &self.claims {
             if *pid == consts::DATE_OF_BIRTH {
@@ -133,6 +177,7 @@ impl Entity {
         None
     }
 
+    /// When the entity stopped existing.
     pub fn end_time(&self) -> Option<DateTime<chrono::offset::Utc>> {
         for (pid, claim) in &self.claims {
             if *pid == consts::DATE_OF_DEATH {
@@ -145,6 +190,7 @@ impl Entity {
     }
 }
 
+/// An error related to entity parsing/creation.
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[non_exhaustive]
 pub enum EntityError {
@@ -369,6 +415,7 @@ impl ClaimValueData {
 }
 
 impl ClaimValue {
+    /// Try to parse a JSON claim to a claim value.
     #[must_use]
     pub fn get_prop_from_snak(mut claim: json::JsonValue, skip_id: bool) -> Option<ClaimValue> {
         let claim_str = take_prop("rank", &mut claim)

src/ids.rs

@@ -3,9 +3,12 @@
 use serde::{Deserialize, Serialize};
 use std::{num::ParseIntError, str::FromStr};
 
+/// An error parsing an ID.
 #[derive(Debug, Clone)]
 pub enum IdParseError {
+    /// The number couldn't be parsed.
     UnparseableNumber(ParseIntError),
+    /// The ID had an invalid prefix letter.
     InvalidPrefix,
 }
 
@@ -14,6 +17,8 @@ macro_rules! id_def {
         #[derive(
             Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize,
         )]
+        #[doc = "A Wikidata"]
+        #[doc = $full_name]
         pub struct $name(pub u64);
 
         impl $name {
@@ -50,6 +55,7 @@ macro_rules! id_def {
             }
         }
         impl std::fmt::Display for $name {
+            /// Display the ID as it would be in a URI.
             fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                 write!(f, concat!($letter, "{}"), self.0)
             }
@@ -63,15 +69,14 @@ id_def!(Lid, "lexeme ID", "L");
 
 /// A lexeme ID and associated form ID
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
-// see id_def! comment about datatype
 pub struct Fid(pub Lid, pub u16);
 
 /// A lexeme ID and assoicated sense ID
 #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]
-// see id_def! comment about datatype
 pub struct Sid(pub Lid, pub u16);
 
 impl ToString for Fid {
+    /// Display the ID as it would be in a URI.
     #[must_use]
     fn to_string(&self) -> String {
         match self {
@@ -81,6 +86,7 @@ impl ToString for Fid {
 }
 
 impl ToString for Sid {
+    /// Display the ID as it would be in a URI.
     #[must_use]
     fn to_string(&self) -> String {
         match self {
@@ -107,7 +113,7 @@ macro_rules! pid_consts (
 macro_rules! qid_unit_suffixes {
     { $($key:ident => $value:expr),+, } => {
         #[must_use]
-        pub fn unit_suffix(qid: Qid) -> Option<&'static str> {
+        pub(super) fn unit_suffix(qid: Qid) -> Option<&'static str> {
             $(
                 if qid == $key {
                     Some($value)
@@ -120,6 +126,13 @@ macro_rules! qid_unit_suffixes {
     };
 }
 
+impl Qid {
+    /// If the Qid is a commonly used unit on Wikidata, get it as a unit suffix.
+    pub fn unit_suffix(self) -> Option<&'static str> {
+        consts::unit_suffix(self)
+    }
+}
+
 #[allow(clippy::unreadable_literal)]
 /// Various IDs for commonly used entities/properties on Wikidata.
 pub mod consts {

src/text.rs

@@ -1,9 +1,10 @@
 use serde::{Deserialize, Serialize};
 
-/// A language used in the Wikibase data model.
+/// A language, as used in the Wikibase data model.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
 pub struct Lang(pub String);
 
+/// Text that is in a certain language.
 #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]
 pub struct Text {
     pub text: String,