More Object docs

src/link.rs

@@ -30,7 +30,7 @@ use std::convert::TryFrom;
 use typed_builder::TypedBuilder;
 
 pub mod kind {
-    //! kinds of links defined by the spec
+    //! Kinds of links defined by the spec
     //!
     //! These types exist only to be statically-typed versions of the associated string. e.g.
     //! `MentionType` -> `"Mention"`
@@ -44,10 +44,10 @@ use self::kind::MentionType;
 ///
 /// Any type implementing AsLink will automatically gain methods provided by LinkExt
 pub trait AsLink<Kind>: markers::Link {
-    /// Immutable borrow of Link<Kind>
+    /// Immutable borrow of `Link<Kind>`
     fn link_ref(&self) -> &Link<Kind>;
 
-    /// Mutable borrow of Link<Kind>
+    /// Mutable borrow of `Link<Kind>`
     fn link_mut(&mut self) -> &mut Link<Kind>;
 }
 

src/object.rs

@@ -1,3 +1,24 @@
+//! Types and traits for dealing with Object attributes
+//!
+//! ```rust
+//! # fn main() -> Result<(), anyhow::Error> {
+//! use activitystreams_new::{
+//!     object::Image,
+//!     prelude::*,
+//!     primitives::XsdAnyUri,
+//! };
+//!
+//! let mut image = Image::default();
+//!
+//! image
+//!     .set_url("https://example.com/image.png".parse::<XsdAnyUri>()?)
+//!     .set_attributed_to("https://example.com/actor".parse::<XsdAnyUri>()?)
+//!     .set_generator("https://example.com/image-generator".parse::<XsdAnyUri>()?)
+//!     .set_icon("https://example.com/icon.png".parse::<XsdAnyUri>()?);
+//! #
+//! # Ok(())
+//! # }
+//! ```
 use crate::{
     base::{AnyBase, AsBase, Base, Extends},
     markers,
@@ -8,41 +29,88 @@ use std::convert::TryFrom;
 use typed_builder::TypedBuilder;
 
 pub mod kind {
+    //! Kinds of objects defined by the spec
+    //!
+    //! These types exist only to be statically-typed versions of the associated string. e.g.
+    //! `PlaceType` -> `"Place"`
+
     pub use activitystreams::object::kind::*;
 }
 
 use self::kind::*;
 
+/// Implementation trait for deriving Object methods for a type
+///
+/// Any type implementing AsObject will automatically gain methods provided by ObjectExt
 pub trait AsObject<Kind>: markers::Object {
+    /// Immutable borrow of `Object<Kind>`
     fn object_ref(&self) -> &Object<Kind>;
+
+    /// Mutable borrow of `Object<Kind>`
     fn object_mut(&mut self) -> &mut Object<Kind>;
 }
 
+/// Implementation trait for deriving ActivityPub Object methods for a type
+///
+/// Any type implementing AsApObject will automatically gain methods provided by ApObjectExt
 pub trait AsApObject<Inner>: markers::Object {
+    /// Immutable borrow of `ApObject<Inner>`
     fn ap_object_ref(&self) -> &ApObject<Inner>;
+
+    /// Mutable borrow of `ApObject<Inner>`
     fn ap_object_mut(&mut self) -> &mut ApObject<Inner>;
 }
 
+/// Implementation trait for deriving Place methods for a type
+///
+/// Any type implementing AsPlace will automatically gain methods provided by PlaceExt
 pub trait AsPlace: markers::Object {
+    /// Immutable borrow of `Place`
     fn place_ref(&self) -> &Place;
+
+    /// Mutable borrow of `Place`
     fn place_mut(&mut self) -> &mut Place;
 }
 
+/// Implementation trait for deriving Profile methods for a type
+///
+/// Any type implementing AsProfile will automatically gain methods provided by ProfileExt
 pub trait AsProfile: markers::Object {
+    /// Immutable borrow of `Profile`
     fn profile_ref(&self) -> &Profile;
+
+    /// Mutable borrow of `Profile`
     fn profile_mut(&mut self) -> &mut Profile;
 }
 
+/// Implementation trait for deriving Relationship methods for a type
+///
+/// Any type implementing AsRelationship will automatically gain methods provided by
+/// RelationshipExt
 pub trait AsRelationship: markers::Object {
+    /// Immutable borrow of `Relationship`
     fn relationship_ref(&self) -> &Relationship;
+
+    /// Mutable borrow of `Relationship`
     fn relationship_mut(&mut self) -> &mut Relationship;
 }
 
+/// Implementation trait for deriving Tombstone methods for a type
+///
+/// Any type implementing AsTombstone will automatically gain methods provided by TombstoneExt
 pub trait AsTombstone: markers::Object {
+    /// Immutable borrow of `Tombstone`
     fn tombstone_ref(&self) -> &Tombstone;
+
+    /// Mutable borrow of `Tombstone`
     fn tombstone_mut(&mut self) -> &mut Tombstone;
 }
 
+/// Helper methods for interacting with Object types
+///
+/// This trait represents methods valid for any ActivityStreams Object.
+///
+/// Documentation for the fields related to these methods can be found on the `Object` struct
 pub trait ObjectExt<Kind>: AsObject<Kind> {
     /// Fetch the attachment for the current object
     ///
@@ -2706,6 +2774,11 @@ pub trait ObjectExt<Kind>: AsObject<Kind> {
     }
 }
 
+/// Helper methods for interacting with ActivityPub Object types
+///
+/// This trait represents methods valid for any ActivityPub Object.
+///
+/// Documentation for the fields related to these methods can be found on the `ApObject` struct
 pub trait ApObjectExt<Inner>: AsApObject<Inner> {
     fn shares<'a>(&'a self) -> Option<&'a XsdAnyUri>
     where
@@ -2989,10 +3062,36 @@ pub trait RelationshipExt: AsRelationship {
         self
     }
 
+    /// Fetch the object for the current object
+    ///
+    /// ```rust
+    /// # use activitystreams_new::object::Relationship;
+    /// # let mut video = Relationship::default();
+    /// #
+    /// use activitystreams_new::prelude::*;
+    ///
+    /// if let Some(object) = video.object() {
+    ///     println!("{:?}", object);
+    /// }
+    /// ```
     fn object(&self) -> Option<&OneOrMany<AnyBase>> {
         self.relationship_ref().object.as_ref()
     }
 
+    /// Set the object for the current object
+    ///
+    /// This overwrites the contents of object
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// use activitystreams_new::prelude::*;
+    /// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
+    /// # let mut video = Relationship::default();
+    ///
+    /// video.set_object("https://example.com".parse::<XsdAnyUri>()?);
+    /// # Ok(())
+    /// # }
+    /// ```
     fn set_object<T>(&mut self, object: T) -> &mut Self
     where
         T: Into<AnyBase>,
@@ -3001,6 +3100,23 @@ pub trait RelationshipExt: AsRelationship {
         self
     }
 
+    /// Set many objects for the current object
+    ///
+    /// This overwrites the contents of object
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// use activitystreams_new::prelude::*;
+    /// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
+    /// # let mut video = Relationship::default();
+    ///
+    /// video.set_many_objects(vec![
+    ///     "https://example.com/one".parse::<XsdAnyUri>()?,
+    ///     "https://example.com/two".parse()?,
+    /// ]);
+    /// # Ok(())
+    /// # }
+    /// ```
     fn set_many_objects<I, T>(&mut self, items: I) -> &mut Self
     where
         I: IntoIterator<Item = T>,
@@ -3011,6 +3127,22 @@ pub trait RelationshipExt: AsRelationship {
         self
     }
 
+    /// Add a object to the current object
+    ///
+    /// This does not overwrite the contents of object, only appends an item
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// use activitystreams_new::prelude::*;
+    /// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
+    /// # let mut video = Relationship::default();
+    ///
+    /// video
+    ///     .add_object("https://example.com/one".parse::<XsdAnyUri>()?)
+    ///     .add_object("https://example.com/two".parse::<XsdAnyUri>()?);
+    /// # Ok(())
+    /// # }
+    /// ```
     fn add_object<T>(&mut self, object: T) -> &mut Self
     where
         T: Into<AnyBase>,
@@ -3026,19 +3158,73 @@ pub trait RelationshipExt: AsRelationship {
         self
     }
 
+    /// Take the object from the current object, leaving nothing
+    ///
+    /// ```rust
+    /// # use activitystreams_new::object::Relationship;
+    /// # let mut video = Relationship::default();
+    /// #
+    /// use activitystreams_new::prelude::*;
+    ///
+    /// if let Some(object) = video.take_object() {
+    ///     println!("{:?}", object);
+    /// }
+    /// ```
     fn take_object(&mut self) -> Option<OneOrMany<AnyBase>> {
         self.relationship_mut().object.take()
     }
 
+    /// Delete the object from the current object
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
+    /// # let mut video = Relationship::default();
+    /// # video.set_object("https://example.com".parse::<XsdAnyUri>()?);
+    /// #
+    /// use activitystreams_new::prelude::*;
+    ///
+    /// assert!(video.object().is_some());
+    /// video.delete_object();
+    /// assert!(video.object().is_none());
+    /// # Ok(())
+    /// # }
+    /// ```
     fn delete_object(&mut self) -> &mut Self {
         self.relationship_mut().object = None;
         self
     }
 
+    /// Fetch the relationship for the current object
+    ///
+    /// ```rust
+    /// # use activitystreams_new::object::Relationship;
+    /// # let mut video = Relationship::default();
+    /// #
+    /// use activitystreams_new::prelude::*;
+    ///
+    /// if let Some(relationship) = video.relationship() {
+    ///     println!("{:?}", relationship);
+    /// }
+    /// ```
     fn relationship(&self) -> Option<&OneOrMany<AnyBase>> {
         self.relationship_ref().relationship.as_ref()
     }
 
+    /// Set the relationship for the current object
+    ///
+    /// This overwrites the contents of relationship
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// use activitystreams_new::prelude::*;
+    /// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
+    /// # let mut video = Relationship::default();
+    ///
+    /// video.set_relationship("https://example.com".parse::<XsdAnyUri>()?);
+    /// # Ok(())
+    /// # }
+    /// ```
     fn set_relationship<T>(&mut self, relationship: T) -> &mut Self
     where
         T: Into<AnyBase>,
@@ -3047,6 +3233,23 @@ pub trait RelationshipExt: AsRelationship {
         self
     }
 
+    /// Set many relationships for the current object
+    ///
+    /// This overwrites the contents of relationship
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// use activitystreams_new::prelude::*;
+    /// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
+    /// # let mut video = Relationship::default();
+    ///
+    /// video.set_many_relationships(vec![
+    ///     "https://example.com/one".parse::<XsdAnyUri>()?,
+    ///     "https://example.com/two".parse()?,
+    /// ]);
+    /// # Ok(())
+    /// # }
+    /// ```
     fn set_many_relationships<I, T>(&mut self, items: I) -> &mut Self
     where
         I: IntoIterator<Item = T>,
@@ -3057,6 +3260,22 @@ pub trait RelationshipExt: AsRelationship {
         self
     }
 
+    /// Add a relationship to the current object
+    ///
+    /// This does not overwrite the contents of relationship, only appends an item
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// use activitystreams_new::prelude::*;
+    /// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
+    /// # let mut video = Relationship::default();
+    ///
+    /// video
+    ///     .add_relationship("https://example.com/one".parse::<XsdAnyUri>()?)
+    ///     .add_relationship("https://example.com/two".parse::<XsdAnyUri>()?);
+    /// # Ok(())
+    /// # }
+    /// ```
     fn add_relationship<T>(&mut self, relationship: T) -> &mut Self
     where
         T: Into<AnyBase>,
@@ -3072,10 +3291,38 @@ pub trait RelationshipExt: AsRelationship {
         self
     }
 
+    /// Take the relationship from the current object, leaving nothing
+    ///
+    /// ```rust
+    /// # use activitystreams_new::object::Relationship;
+    /// # let mut video = Relationship::default();
+    /// #
+    /// use activitystreams_new::prelude::*;
+    ///
+    /// if let Some(relationship) = video.take_relationship() {
+    ///     println!("{:?}", relationship);
+    /// }
+    /// ```
     fn take_relationship(&mut self) -> Option<OneOrMany<AnyBase>> {
         self.relationship_mut().relationship.take()
     }
 
+    /// Delete the relationship from the current object
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// # use activitystreams_new::{object::Relationship, primitives::XsdAnyUri};
+    /// # let mut video = Relationship::default();
+    /// # video.set_relationship("https://example.com".parse::<XsdAnyUri>()?);
+    /// #
+    /// use activitystreams_new::prelude::*;
+    ///
+    /// assert!(video.relationship().is_some());
+    /// video.delete_relationship();
+    /// assert!(video.relationship().is_none());
+    /// # Ok(())
+    /// # }
+    /// ```
     fn delete_relationship(&mut self) -> &mut Self {
         self.relationship_mut().relationship = None;
         self
@@ -3083,10 +3330,36 @@ pub trait RelationshipExt: AsRelationship {
 }
 
 pub trait TombstoneExt: AsTombstone {
+    /// Fetch the former_type for the current object
+    ///
+    /// ```rust
+    /// # use activitystreams_new::object::Tombstone;
+    /// # let mut video = Tombstone::default();
+    /// #
+    /// use activitystreams_new::prelude::*;
+    ///
+    /// if let Some(former_type) = video.former_type() {
+    ///     println!("{:?}", former_type);
+    /// }
+    /// ```
     fn former_type(&self) -> Option<&OneOrMany<AnyBase>> {
         self.tombstone_ref().former_type.as_ref()
     }
 
+    /// Set the former_type for the current object
+    ///
+    /// This overwrites the contents of former_type
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// use activitystreams_new::prelude::*;
+    /// # use activitystreams_new::{object::Tombstone, primitives::XsdAnyUri};
+    /// # let mut video = Tombstone::default();
+    ///
+    /// video.set_former_type("https://example.com".parse::<XsdAnyUri>()?);
+    /// # Ok(())
+    /// # }
+    /// ```
     fn set_former_type<T>(&mut self, former_type: T) -> &mut Self
     where
         T: Into<AnyBase>,
@@ -3095,6 +3368,23 @@ pub trait TombstoneExt: AsTombstone {
         self
     }
 
+    /// Set many former_types for the current object
+    ///
+    /// This overwrites the contents of former_type
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// use activitystreams_new::prelude::*;
+    /// # use activitystreams_new::{object::Tombstone, primitives::XsdAnyUri};
+    /// # let mut video = Tombstone::default();
+    ///
+    /// video.set_many_former_types(vec![
+    ///     "https://example.com/one".parse::<XsdAnyUri>()?,
+    ///     "https://example.com/two".parse()?,
+    /// ]);
+    /// # Ok(())
+    /// # }
+    /// ```
     fn set_many_former_types<I, T>(&mut self, items: I) -> &mut Self
     where
         I: IntoIterator<Item = T>,
@@ -3105,6 +3395,22 @@ pub trait TombstoneExt: AsTombstone {
         self
     }
 
+    /// Add a former_type to the current object
+    ///
+    /// This does not overwrite the contents of former_type, only appends an item
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// use activitystreams_new::prelude::*;
+    /// # use activitystreams_new::{object::Tombstone, primitives::XsdAnyUri};
+    /// # let mut video = Tombstone::default();
+    ///
+    /// video
+    ///     .add_former_type("https://example.com/one".parse::<XsdAnyUri>()?)
+    ///     .add_former_type("https://example.com/two".parse::<XsdAnyUri>()?);
+    /// # Ok(())
+    /// # }
+    /// ```
     fn add_former_type<T>(&mut self, former_type: T) -> &mut Self
     where
         T: Into<AnyBase>,
@@ -3120,10 +3426,38 @@ pub trait TombstoneExt: AsTombstone {
         self
     }
 
+    /// Take the former_type from the current object, leaving nothing
+    ///
+    /// ```rust
+    /// # use activitystreams_new::object::Tombstone;
+    /// # let mut video = Tombstone::default();
+    /// #
+    /// use activitystreams_new::prelude::*;
+    ///
+    /// if let Some(former_type) = video.take_former_type() {
+    ///     println!("{:?}", former_type);
+    /// }
+    /// ```
     fn take_former_type(&mut self) -> Option<OneOrMany<AnyBase>> {
         self.tombstone_mut().former_type.take()
     }
 
+    /// Delete the former_type from the current object
+    ///
+    /// ```rust
+    /// # fn main() -> Result<(), anyhow::Error> {
+    /// # use activitystreams_new::{object::Tombstone, primitives::XsdAnyUri};
+    /// # let mut video = Tombstone::default();
+    /// # video.set_former_type("https://example.com".parse::<XsdAnyUri>()?);
+    /// #
+    /// use activitystreams_new::prelude::*;
+    ///
+    /// assert!(video.former_type().is_some());
+    /// video.delete_former_type();
+    /// assert!(video.former_type().is_none());
+    /// # Ok(())
+    /// # }
+    /// ```
     fn delete_former_type(&mut self) -> &mut Self {
         self.tombstone_mut().former_type = None;
         self