Finish documentation

Cargo.toml

@@ -11,6 +11,13 @@ keywords = ["activitystreams", "activitypub"]
 activitystreams-traits = { version = "0.1", path = "activitystreams-traits" }
 activitystreams-types = { version = "0.1", path = "activitystreams-types" }
 
+[dev-dependencies]
+failure = "0.1"
+serde = "1.0"
+serde_derive = "1.0"
+serde_json = "1.0"
+activitystreams-derive = { version = "0.1", path = "activitystreams-derive" }
+
 [workspace]
 members = [
     "activitystreams-derive",

README.md

@@ -0,0 +1,143 @@
+# ActivityStreams
+__A set of Traits and Types that make up the Activity Streams specification__
+
+## Usage
+
+### Basic usage
+For basic use, add the following to your Cargo.toml
+```toml
+# Cargo.toml
+
+activitystreams = "0.1"
+```
+
+And then use it in your project
+```rust
+extern crate activitystreams;
+extern crate failure;
+extern crate serde;
+#[macro_use]
+extern crate serde_derive;
+extern crate serde_json;
+
+use activitystreams::{context, Object, Actor, object::Profile};
+use failure::Error;
+
+#[derive(Clone, Debug, Default, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Persona {
+    #[serde(rename = "@context")]
+    context: serde_json::Value,
+
+    #[serde(rename = "type")]
+    kind: String,
+}
+
+impl Object for Persona {}
+impl Actor for Persona {}
+
+fn run() -> Result<(), Error> {
+    let mut profile = Profile::default();
+
+    profile.profile.set_describes_object(Persona {
+        context: serde_json::to_value(context())?,
+
+        kind: "Persona".to_owned(),
+    })?;
+
+    profile.object_props.set_context_object(context())?;
+
+    let profile_string = serde_json::to_string(&profile)?;
+
+    let profile: Profile = serde_json::from_str(&profile_string)?;
+
+    Ok(())
+}
+```
+
+### Advanced Usage
+Add the required crates to your `Cargo.toml`
+```toml
+# Cargo.toml
+
+activitystreams-derive = "0.1"
+activitystreams-traits = "0.1"
+serde = "1.0"
+serde_derive = "1.0"
+serde_json = "1.0"
+```
+
+And then in your project
+```rust
+#[macro_use]
+extern crate activitystreams_derive;
+extern crate activitystreams_traits;
+extern crate activitystreams_types;
+extern crate failure;
+extern crate serde;
+#[macro_use]
+extern crate serde_derive;
+extern crate serde_json;
+
+use activitystreams_traits::{Link, Object};
+use activitystreams_types::{CustomLink, link::Mention};
+use failure::Error;
+
+/// Using the UnitString derive macro
+///
+/// This macro implements Serialize and Deserialize for the given type, making this type
+/// represent the string "SomeKind" in JSON.
+#[derive(Clone, Debug, Default, UnitString)]
+#[activitystreams(SomeKind)]
+pub struct MyKind;
+
+/// Using the Properties derive macro
+///
+/// This macro generates getters and setters for the associated fields.
+#[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
+#[serde(rename_all = "camelCase")]
+pub struct MyProperties {
+    /// Derive getters and setters for @context with Link and Object traits.
+    #[serde(rename = "@context")]
+    #[activitystreams(ab(Object, Link))]
+    pub context: Option<serde_json::Value>,
+
+    /// Use the UnitString MyKind to enforce the type of the object by "SomeKind"
+    pub kind: MyKind,
+
+    /// Derive getters and setters for required_key with String type.
+    ///
+    /// In the Activity Streams spec, 'functional' means there can only be one item for this
+    /// key. This means all fields not labeled 'functional' can also be serialized/deserialized
+    /// as Vec<T>.
+    #[activitystreams(concrete(String), functional)]
+    pub required_key: serde_json::Value,
+}
+
+fn run() -> Result<(), Error> {
+    let mut props = MyProperties::default();
+
+    props.set_required_key_string("Hey".to_owned())?;
+
+    let my_link = CustomLink::new(Mention::default(), props);
+
+    let my_link_string = serde_json::to_string(&my_link)?;
+
+    let my_link: CustomLink<Mention, MyProperties> = serde_json::from_str(&my_link_string)?;
+
+    Ok(())
+}
+```
+
+## Contributing
+Feel free to open issues for anything you find an issue with. Please note that any contributed code will be licensed under the GPLv3.
+
+## License
+
+Copyright © 2018 Riley Trautman
+
+ActivityStreams is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+ActivityStreams is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. This file is part of ActivityStreams.
+
+You should have received a copy of the GNU General Public License along with ActivityStreams. If not, see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).

activitystreams-traits/src/error.rs

@@ -20,7 +20,7 @@
 use std::result;
 
 /// The Error type
-#[derive(Copy, Clone, Debug, Fail)]
+#[derive(Copy, Clone, Debug, Eq, Fail, PartialEq)]
 pub enum Error {
     /// This error occurs when an Activity Streams type does not contain a requested value
     #[fail(display = "Key not present")]

activitystreams-types/Cargo.toml

@@ -15,3 +15,6 @@ mime = "0.3"
 serde = "1.0"
 serde_derive = "1.0"
 serde_json = "1.0"
+
+[dev-dependencies]
+failure = "0.1"

activitystreams-types/README.md

@@ -0,0 +1,47 @@
+# ActivityStreams Types
+__A base set of types from the Activity Streams specification.__
+
+## Usage
+First, add the crate to your cargo.toml
+```toml
+# Cargo.toml
+
+activitystreams-types = "0.1"
+```
+
+Then use it in your project!
+```rust
+// in your project
+
+extern crate activitystreams_types;
+extern crate failure;
+extern crate serde_json;
+
+use activitystreams_types::{context, link::Mention};
+use failure::Error;
+
+fn run() -> Result<(), Error> {
+    /// A Mention is the only predefined Link type in the Activity Streams spec
+    let mut mention = Mention::default();
+    mention.link_props.set_context_object(context())?;
+
+    let mention_string = serde_json::to_string(&mention)?;
+
+    let mention: Mention = serde_json::from_str(&mention_string)?;
+
+    Ok(())
+}
+```
+
+## Contributing
+Feel free to open issues for anything you find an issue with. Please note that any contributed code will be licensed under the GPLv3.
+
+## License
+
+Copyright © 2018 Riley Trautman
+
+ActivityStreams Types is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
+
+ActivityStreams Types is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. This file is part of ActivityStreams Types.
+
+You should have received a copy of the GNU General Public License along with ActivityStreams Types. If not, see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).

activitystreams-types/src/activity/accept.rs

@@ -23,21 +23,42 @@ use serde_json;
 use super::{kind::AcceptType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor accepts the object.
+///
+/// The target property can be used in certain circumstances to indicate the context into which the
+/// object has been accepted.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Accept {
     #[serde(rename = "type")]
-    kind: AcceptType,
+    pub kind: AcceptType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/add.rs

@@ -23,21 +23,43 @@ use serde_json;
 use super::{kind::AddType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor has added the object to the target.
+///
+/// If the target property is not explicitly specified, the target would need to be determined
+/// implicitly by context. The origin can be used to identify the context from which the object
+/// originated.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Add {
     #[serde(rename = "type")]
-    kind: AddType,
+    pub kind: AddType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/amove.rs

@@ -23,29 +23,66 @@ use serde_json;
 use super::{kind::MoveType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor has moved object from origin to target.
+///
+/// If the origin or target are not specified, either can be determined by context.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct AMove {
     #[serde(rename = "type")]
-    kind: MoveType,
+    pub kind: MoveType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Describes an indirect object of the activity from which the activity is directed.
+    ///
+    /// The precise meaning of the origin is the object of the English preposition "from". For
+    /// instance, in the activity "John moved an item to List B from List A", the origin of the
+    /// activity is "List A".
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    origin: Option<serde_json::Value>,
+    pub origin: Option<serde_json::Value>,
 
+    /// Describes the indirect object, or target, of the activity.
+    ///
+    /// The precise meaning of the target is largely dependent on the type of action being
+    /// described but will often be the object of the English preposition "to". For instance, in
+    /// the activity "John added a movie to his wishlist", the target of the activity is John's
+    /// wishlist. An activity can have more than one target
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    target: Option<serde_json::Value>,
+    pub target: Option<serde_json::Value>,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/announce.rs

@@ -23,25 +23,54 @@ use serde_json;
 use super::{kind::AnnounceType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor is calling the target's attention the object.
+///
+/// The origin typically has no defined meaning.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Announce {
     #[serde(rename = "type")]
-    kind: AnnounceType,
+    pub kind: AnnounceType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Describes the indirect object, or target, of the activity.
+    ///
+    /// The precise meaning of the target is largely dependent on the type of action being
+    /// described but will often be the object of the English preposition "to". For instance, in
+    /// the activity "John added a movie to his wishlist", the target of the activity is John's
+    /// wishlist. An activity can have more than one target
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    target: Option<serde_json::Value>,
+    pub target: Option<serde_json::Value>,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/arrive.rs

@@ -23,24 +23,43 @@ use serde_json;
 use super::{kind::ArriveType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// An IntransitiveActivity that indicates that the actor has arrived at the location.
+///
+/// The origin can be used to identify the context from which the actor originated. The target
+/// typically has no defined meaning.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Arrive {
     #[serde(rename = "type")]
-    kind: ArriveType,
+    pub kind: ArriveType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// Describes an indirect object of the activity from which the activity is directed.
+    ///
+    /// The precise meaning of the origin is the object of the English preposition "from". For
+    /// instance, in the activity "John moved an item to List B from List A", the origin of the
+    /// activity is "List A".
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    location: serde_json::Value,
+    pub origin: serde_json::Value,
-
-    #[activitystreams(ab(Object, Link))]
-    origin: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/block.rs

@@ -23,21 +23,43 @@ use serde_json;
 use super::{kind::BlockType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor is blocking the object.
+///
+/// Blocking is a stronger form of Ignore. The typical use is to support social systems that allow
+/// one user to block activities or content of other users. The target and origin typically have no
+/// defined meaning.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Block {
     #[serde(rename = "type")]
-    kind: BlockType,
+    pub kind: BlockType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/create.rs

@@ -23,21 +23,39 @@ use serde_json;
 use super::{kind::CreateType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor has created the object.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Create {
     #[serde(rename = "type")]
-    kind: CreateType,
+    pub kind: CreateType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/delete.rs

@@ -23,25 +23,53 @@ use serde_json;
 use super::{kind::DeleteType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor has deleted the object.
+///
+/// If specified, the origin indicates the context from which the object was deleted.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Delete {
     #[serde(rename = "type")]
-    kind: DeleteType,
+    pub kind: DeleteType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Describes an indirect object of the activity from which the activity is directed.
+    ///
+    /// The precise meaning of the origin is the object of the English preposition "from". For
+    /// instance, in the activity "John moved an item to List B from List A", the origin of the
+    /// activity is "List A".
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    origin: Option<serde_json::Value>,
+    pub origin: Option<serde_json::Value>,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/dislike.rs

@@ -23,21 +23,39 @@ use serde_json;
 use super::{kind::DislikeType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor dislikes the object.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Dislike {
     #[serde(rename = "type")]
-    kind: DislikeType,
+    pub kind: DislikeType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/flag.rs

@@ -23,21 +23,42 @@ use serde_json;
 use super::{kind::FlagType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor is "flagging" the object.
+///
+/// Flagging is defined in the sense common to many social platforms as reporting content as being
+/// inappropriate for any number of reasons.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Flag {
     #[serde(rename = "type")]
-    kind: FlagType,
+    pub kind: FlagType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/follow.rs

@@ -23,21 +23,43 @@ use serde_json;
 use super::{kind::FollowType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor is "following" the object.
+///
+/// Following is defined in the sense typically used within Social systems in which the actor is
+/// interested in any activity performed by or on the object. The target and origin typically have
+/// no defined meaning.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Follow {
     #[serde(rename = "type")]
-    kind: FollowType,
+    pub kind: FollowType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/ignore.rs

@@ -23,21 +23,41 @@ use serde_json;
 use super::{kind::IgnoreType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor is ignoring the object.
+///
+/// The target and origin typically have no defined meaning.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Ignore {
     #[serde(rename = "type")]
-    kind: IgnoreType,
+    pub kind: IgnoreType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/invite.rs

@@ -23,24 +23,52 @@ use serde_json;
 use super::{kind::InviteType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// A specialization of Offer in which the actor is extending an invitation for the object to the
+/// target.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Invite {
     #[serde(rename = "type")]
-    kind: InviteType,
+    pub kind: InviteType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Describes the indirect object, or target, of the activity.
+    ///
+    /// The precise meaning of the target is largely dependent on the type of action being
+    /// described but will often be the object of the English preposition "to". For instance, in
+    /// the activity "John added a movie to his wishlist", the target of the activity is John's
+    /// wishlist. An activity can have more than one target
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    target: serde_json::Value,
+    pub target: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/join.rs

@@ -23,21 +23,41 @@ use serde_json;
 use super::{kind::JoinType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor has joined the object.
+///
+/// The target and origin typically have no defined meaning
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Join {
     #[serde(rename = "type")]
-    kind: JoinType,
+    pub kind: JoinType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/kind.rs

@@ -17,6 +17,8 @@
  * along with ActivityStreams Types.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+//! Namespace for Unit Structs that serialize to strings
+
 #[derive(Clone, Debug, Default, UnitString)]
 #[activitystreams(Accept)]
 pub struct AcceptType;

activitystreams-types/src/activity/leave.rs

@@ -23,21 +23,41 @@ use serde_json;
 use super::{kind::LeaveType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor has left the object.
+///
+/// The target and origin typically have no meaning.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Leave {
     #[serde(rename = "type")]
-    kind: LeaveType,
+    pub kind: LeaveType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/like.rs

@@ -23,21 +23,41 @@ use serde_json;
 use super::{kind::LikeType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor likes, recommends or endorses the object.
+///
+/// The target and origin typically have no defined meaning.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Like {
     #[serde(rename = "type")]
-    kind: LikeType,
+    pub kind: LikeType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/listen.rs

@@ -23,21 +23,39 @@ use serde_json;
 use super::{kind::ListenType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor has listened to the object.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Listen {
     #[serde(rename = "type")]
     kind: ListenType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
     actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
     object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/offer.rs

@@ -23,25 +23,54 @@ use serde_json;
 use super::{kind::OfferType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor is offering the object.
+///
+/// If specified, the target indicates the entity to which the object is being offered.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Offer {
     #[serde(rename = "type")]
-    kind: OfferType,
+    pub kind: OfferType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Describes the indirect object, or target, of the activity.
+    ///
+    /// The precise meaning of the target is largely dependent on the type of action being
+    /// described but will often be the object of the English preposition "to". For instance, in
+    /// the activity "John added a movie to his wishlist", the target of the activity is John's
+    /// wishlist. An activity can have more than one target
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    target: Option<serde_json::Value>,
+    pub target: Option<serde_json::Value>,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/properties.rs

@@ -59,14 +59,28 @@
 use activitystreams_traits::{Link, Object};
 use serde_json;
 
+/// Activity objects are specializations of the base Object type that provide information about
+/// actions that have either already occurred, are in the process of occurring, or may occur in the
+/// future.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct ActivityProperties {
+    /// Describes the result of the activity.
+    ///
+    /// For instance, if a particular action results in the creation of a new resource, the result
+    /// property can be used to describe that new resource.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Funcitonal: false
     #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    result: Option<serde_json::Value>,
+    pub result: Option<serde_json::Value>,
 
+    /// Identifies one or more objects used (or to be used) in the completion of an `Activity`.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Funcitonal: false
     #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    instrument: Option<serde_json::Value>,
+    pub instrument: Option<serde_json::Value>,
 }

activitystreams-types/src/activity/question.rs

@@ -23,23 +23,47 @@ use serde_json;
 use super::{kind::QuestionType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Represents a question being asked.
+///
+/// Question objects are an extension of IntransitiveActivity. That is, the Question object is an
+/// Activity, but the direct object is the question itself and therefore it would not contain an
+/// object property.
+///
+/// Either of the anyOf and oneOf properties MAY be used to express possible answers, but a
+/// Question object MUST NOT have both properties.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Question {
     #[serde(rename = "type")]
-    kind: QuestionType,
+    pub kind: QuestionType,
 
-    #[serde(skip_serializing_if = "Vec::is_empty", default = "Vec::new")]
+    /// Identifies an exclusive option for a Question.
+    ///
+    /// Use of `one_of` implies that the Question can have only a single answer. To indicate that a
+    /// `Question` can have multiple answers, use `any_of`.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
+    #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    one_of: Vec<serde_json::Value>,
+    pub one_of: Option<serde_json::Value>,
 
-    #[serde(skip_serializing_if = "Vec::is_empty", default = "Vec::new")]
+    /// Identifies an inclusive option for a Question.
+    ///
+    /// Use of `any_of` implies that the Question can have multiple answers. To indicate that a
+    /// `Question` can have only one answer, use `one_of`.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
+    #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    any_of: Vec<serde_json::Value>,
+    pub any_of: Option<serde_json::Value>,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/read.rs

@@ -23,21 +23,39 @@ use serde_json;
 use super::{kind::ReadType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor has read the object.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Read {
     #[serde(rename = "type")]
-    kind: ReadType,
+    pub kind: ReadType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/reject.rs

@@ -23,21 +23,41 @@ use serde_json;
 use super::{kind::RejectType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor is rejecting the object.
+///
+/// The target and origin typically have no defined meaning.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Reject {
     #[serde(rename = "type")]
-    kind: RejectType,
+    pub kind: RejectType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/remove.rs

@@ -23,29 +23,66 @@ use serde_json;
 use super::{kind::RemoveType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor is removing the object.
+///
+/// If specified, the origin indicates the context from which the object is being removed.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Remove {
     #[serde(rename = "type")]
-    kind: RemoveType,
+    pub kind: RemoveType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Describes an indirect object of the activity from which the activity is directed.
+    ///
+    /// The precise meaning of the origin is the object of the English preposition "from". For
+    /// instance, in the activity "John moved an item to List B from List A", the origin of the
+    /// activity is "List A".
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    origin: Option<serde_json::Value>,
+    pub origin: Option<serde_json::Value>,
 
+    /// Describes the indirect object, or target, of the activity.
+    ///
+    /// The precise meaning of the target is largely dependent on the type of action being
+    /// described but will often be the object of the English preposition "to". For instance, in
+    /// the activity "John added a movie to his wishlist", the target of the activity is John's
+    /// wishlist. An activity can have more than one target
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    target: Option<serde_json::Value>,
+    pub target: Option<serde_json::Value>,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/tentative_accept.rs

@@ -23,21 +23,39 @@ use serde_json;
 use super::{kind::TentativeAcceptType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// A specialization of Accept indicating that the acceptance is tentative.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct TentativeAccept {
     #[serde(rename = "type")]
-    kind: TentativeAcceptType,
+    pub kind: TentativeAcceptType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/tentative_reject.rs

@@ -23,21 +23,39 @@ use serde_json;
 use super::{kind::TentativeRejectType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// A specialization of Reject in which the rejection is considered tentative.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct TentativeReject {
     #[serde(rename = "type")]
-    kind: TentativeRejectType,
+    pub kind: TentativeRejectType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/travel.rs

@@ -23,26 +23,57 @@ use serde_json;
 use super::{kind::TravelType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor is traveling to target from origin.
+///
+/// Travel is an IntransitiveObject whose actor specifies the direct object. If the target or
+/// origin are not specified, either can be determined by context.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Travel {
     #[serde(rename = "type")]
-    kind: TravelType,
+    pub kind: TravelType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// Describes an indirect object of the activity from which the activity is directed.
+    ///
+    /// The precise meaning of the origin is the object of the English preposition "from". For
+    /// instance, in the activity "John moved an item to List B from List A", the origin of the
+    /// activity is "List A".
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    origin: Option<serde_json::Value>,
+    pub origin: Option<serde_json::Value>,
 
+    /// Describes the indirect object, or target, of the activity.
+    ///
+    /// The precise meaning of the target is largely dependent on the type of action being
+    /// described but will often be the object of the English preposition "to". For instance, in
+    /// the activity "John added a movie to his wishlist", the target of the activity is John's
+    /// wishlist. An activity can have more than one target
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[serde(skip_serializing_if = "Option::is_none")]
     #[activitystreams(ab(Object, Link))]
-    target: Option<serde_json::Value>,
+    pub target: Option<serde_json::Value>,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/undo.rs

@@ -23,21 +23,45 @@ use serde_json;
 use super::{kind::UndoType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor is undoing the object.
+///
+/// In most cases, the object will be an Activity describing some previously performed action (for
+/// instance, a person may have previously "liked" an article but, for whatever reason, might
+/// choose to undo that like at some later point in time).
+///
+/// The target and origin typically have no defined meaning.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Undo {
     #[serde(rename = "type")]
-    kind: UndoType,
+    pub kind: UndoType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/update.rs

@@ -23,21 +23,44 @@ use serde_json;
 use super::{kind::UpdateType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor has updated the object.
+///
+/// Note, however, that this vocabulary does not define a mechanism for describing the actual set
+/// of modifications made to object.
+///
+/// The target and origin typically have no defined meaning.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct Update {
     #[serde(rename = "type")]
-    kind: UpdateType,
+    pub kind: UpdateType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/activity/view.rs

@@ -23,21 +23,39 @@ use serde_json;
 use super::{kind::ViewType, properties::ActivityProperties};
 use object::properties::ObjectProperties;
 
+/// Indicates that the actor has viewed the object.
 #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
 #[serde(rename_all = "camelCase")]
 pub struct View {
     #[serde(rename = "type")]
-    kind: ViewType,
+    pub kind: ViewType,
 
+    /// Describes one or more entities that either performed or are expected to perform the
+    /// activity.
+    ///
+    /// Any single activity can have multiple actors. The actor MAY be specified using an indirect
+    /// Link.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    actor: serde_json::Value,
+    pub actor: serde_json::Value,
 
+    /// When used within an Activity, describes the direct object of the activity.
+    ///
+    /// For instance, in the activity "John added a movie to his wishlist", the object of the
+    /// activity is the movie added.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
     #[activitystreams(ab(Object, Link))]
-    object: serde_json::Value,
+    pub object: serde_json::Value,
 
+    /// Adds all valid object properties to this struct
     #[serde(flatten)]
     pub object_props: ObjectProperties,
 
+    /// Adds all valid activity properties to this struct
     #[serde(flatten)]
     pub activity_props: ActivityProperties,
 }

activitystreams-types/src/lib.rs

@@ -17,6 +17,36 @@
  * along with ActivityStreams Types.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+//! ActivityStreams Types
+//!
+//! This crate defines the base set of types from the Activity Streams specification.
+//!
+//! ## Example Usage
+//! ```rust
+//! extern crate activitystreams_types;
+//! extern crate failure;
+//! extern crate serde_json;
+//!
+//! use activitystreams_types::{context, link::Mention};
+//! use failure::Error;
+//!
+//! fn run() -> Result<(), Error> {
+//!     /// A Mention is the only predefined Link type in the Activity Streams spec
+//!     let mut mention = Mention::default();
+//!     mention.link_props.set_context_object(context())?;
+//!
+//!     let mention_string = serde_json::to_string(&mention)?;
+//!
+//!     let mention: Mention = serde_json::from_str(&mention_string)?;
+//!
+//!     Ok(())
+//! }
+//! #
+//! # fn main() {
+//! #     run().unwrap();
+//! # }
+//! ```
+
 #[macro_use]
 extern crate activitystreams_derive;
 extern crate activitystreams_traits;
@@ -25,13 +55,17 @@ extern crate mime;
 extern crate serde;
 #[macro_use]
 extern crate serde_derive;
-#[macro_use]
 extern crate serde_json;
 
-pub fn context() -> serde_json::Value {
+/// Define a simple wrapper around a string for this crate's main Context type
-    json!({
+#[derive(Clone, Debug, Deserialize, Serialize)]
-        "one": "two",
+pub struct ContextObject(pub String);
-    })
+
+impl activitystreams_traits::Object for ContextObject {}
+
+/// The context associated with all of the Activity Streams types defined in the crate.
+pub fn context() -> ContextObject {
+    ContextObject("https://www.w3.org/ns/activitystreams".to_owned())
 }
 
 pub mod activity;

activitystreams-types/src/link/properties.rs

@@ -84,6 +84,18 @@ pub struct LinkProperties {
     #[activitystreams(concrete(String), functional)]
     pub id: Option<serde_json::Value>,
 
+    /// Identifies the context within which the object exists or an activity was performed.
+    ///
+    /// The notion of "context" used is intentionally vague. The intended function is to serve as a
+    /// means of grouping objects and activities that share a common originating context or purpose.
+    /// An example could be all activities relating to a common project or event.
+    ///
+    /// - Range: `Object` | `Link`
+    /// - Functional: false
+    #[serde(skip_serializing_if = "Option::is_none", rename = "@context")]
+    #[activitystreams(ab(Object, Link))]
+    pub context: Option<serde_json::Value>,
+
     // TODO: rdf:langString
     /// A simple, human-readable, plain-text name for the object.
     ///

src/activity.rs

@@ -17,5 +17,20 @@
  * along with ActivityStreams.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-pub use activitystreams_traits::{Activity, IntransitiveActivity};
+//! Activity traits and types
+
+/// An Activity is a subtype of `Object` that describes some form of action that may happen, is
+/// currently happening, or has already happened.
+///
+/// The `Activity` type itself serves as an abstract base type for all types of activities. It is
+/// important to note that the `Activity` type itself does not carry any specific semantics about
+/// the kind of action being taken.
+pub use activitystreams_traits::Activity;
+
+/// Instances of `IntransitiveActivity` are a subtype of `Activity` representing intransitive
+/// actions.
+///
+/// The `object` property is therefore inappropriate for these activities.
+pub use activitystreams_traits::IntransitiveActivity;
+
 pub use activitystreams_types::activity::*;

src/actor.rs

@@ -17,5 +17,27 @@
  * along with ActivityStreams.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+//! Actor traits and types
+
+/// `Actor` types are `Object` types that are capable of performing activities.
+///
+/// This specification intentionally defines `Actors` in only the most generalized way, stopping
+/// short of defining semantically specific properties for each. All Actor objects are
+/// specializations of `Object` and inherit all of the core properties common to all Objects.
+/// External vocabularies can be used to express additional detail not covered by the Activity
+/// Vocabulary. VCard [[vcard-rdf](https://www.w3.org/TR/vcard-rdf/) SHOULD be used to provide
+/// additional metadata for `Person`, `Group`, and `Organization` instances.
+///
+/// While implementations are free to introduce new types of Actors beyond those defined by the
+/// Activity Vocabulary, interoperability issues can arise when applications rely too much on
+/// extension types that are not recognized by other implementations. Care should be taken to not
+/// unduly overlap with or duplicate the existing `Actor` types.
+///
+/// When an implementation uses an extension type that overlaps with a core vocabulary type, the
+/// implementation MUST also specify the core vocabulary type. For instance, some vocabularies
+/// (e.g. VCard) define their own types for describing people. An implementation that wishes, for
+/// example, to use a `vcard:Individual` as an `Actor` MUST also identify that `Actor` as a
+/// `Person`.
 pub use activitystreams_traits::Actor;
+
 pub use activitystreams_types::actor::*;

src/collection.rs

@@ -17,5 +17,29 @@
  * along with ActivityStreams.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-pub use activitystreams_traits::{Collection, CollectionPage};
+//! Collection traits and types
+
+/// A Collection is a subtype of `Object` that represents ordered or unordered sets of `Object` or
+/// `Link` instances.
+///
+/// The items within a Collection can be ordered or unordered. The OrderedCollection type MAY be
+/// used to identify a Collection whose items are always ordered. In the JSON serialization, the
+/// unordered items of a Collection are represented using the items property while ordered items
+/// are represented using the orderedItems property.
+///
+/// `UnorderedCollection` and `OrderedCollection` types are provided by the `activitystreams-types`
+/// crate.
+pub use activitystreams_traits::Collection;
+
+/// Used to represent distinct subsets of items from a Collection.
+///
+/// A `Collection` can contain a large number of items. Often, it becomes impractical for an
+/// implementation to serialize every item contained by a `Collection` using the items (or
+/// `ordered_items`) property alone. In such cases, the items within a `Collection` can be divided
+/// into distinct subsets or "pages". A page is identified using the `CollectionPage` type.
+///
+/// `UnorderedCollectionPage` and `OrderedCollectionPage` types are provied by the
+/// `activitystreams-types` crate.
+pub use activitystreams_traits::CollectionPage;
+
 pub use activitystreams_types::collection::*;

src/error.rs

@@ -17,4 +17,10 @@
  * along with ActivityStreams.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-pub use activitystreams_traits::{Error, Result};
+//! Error traits and types
+
+/// The Error type
+pub use activitystreams_traits::Error;
+
+/// An alias for Result<T, Error>
+pub use activitystreams_traits::Result;

src/lib.rs

@@ -17,13 +17,134 @@
  * along with ActivityStreams.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+//! ActivityStreams
+//!
+//! A set of Traits and Types that make up the Activity Streams specification
+//!
+//! ## Examples
+//!
+//! ### Basic
+//!
+//! ```rust
+//! extern crate activitystreams;
+//! extern crate failure;
+//! extern crate serde;
+//! #[macro_use]
+//! extern crate serde_derive;
+//! extern crate serde_json;
+//!
+//! use activitystreams::{context, Object, Actor, object::Profile};
+//! use failure::Error;
+//!
+//! #[derive(Clone, Debug, Default, Deserialize, Serialize)]
+//! #[serde(rename_all = "camelCase")]
+//! pub struct Persona {
+//!     #[serde(rename = "@context")]
+//!     context: serde_json::Value,
+//!
+//!     #[serde(rename = "type")]
+//!     kind: String,
+//! }
+//!
+//! impl Object for Persona {}
+//! impl Actor for Persona {}
+//!
+//! fn run() -> Result<(), Error> {
+//!     let mut profile = Profile::default();
+//!
+//!     profile.profile.set_describes_object(Persona {
+//!         context: serde_json::to_value(context())?,
+//!
+//!         kind: "Persona".to_owned(),
+//!     })?;
+//!
+//!     profile.object_props.set_context_object(context())?;
+//!
+//!     let profile_string = serde_json::to_string(&profile)?;
+//!
+//!     let profile: Profile = serde_json::from_str(&profile_string)?;
+//!
+//!     Ok(())
+//! }
+//! #
+//! # fn main() {
+//! #   run().unwrap();
+//! # }
+//! ```
+//!
+//! ### Advanced
+//!
+//! ```rust
+//! #[macro_use]
+//! extern crate activitystreams_derive;
+//! extern crate activitystreams_traits;
+//! extern crate activitystreams_types;
+//! extern crate failure;
+//! extern crate serde;
+//! #[macro_use]
+//! extern crate serde_derive;
+//! extern crate serde_json;
+//!
+//! use activitystreams_traits::{Link, Object};
+//! use activitystreams_types::{CustomLink, link::Mention};
+//! use failure::Error;
+//!
+//! /// Using the UnitString derive macro
+//! ///
+//! /// This macro implements Serialize and Deserialize for the given type, making this type
+//! /// represent the string "SomeKind" in JSON.
+//! #[derive(Clone, Debug, Default, UnitString)]
+//! #[activitystreams(SomeKind)]
+//! pub struct MyKind;
+//!
+//! /// Using the Properties derive macro
+//! ///
+//! /// This macro generates getters and setters for the associated fields.
+//! #[derive(Clone, Debug, Default, Deserialize, Serialize, Properties)]
+//! #[serde(rename_all = "camelCase")]
+//! pub struct MyProperties {
+//!     /// Derive getters and setters for @context with Link and Object traits.
+//!     #[serde(rename = "@context")]
+//!     #[activitystreams(ab(Object, Link))]
+//!     pub context: Option<serde_json::Value>,
+//!
+//!     /// Use the UnitString MyKind to enforce the type of the object by "SomeKind"
+//!     pub kind: MyKind,
+//!
+//!     /// Derive getters and setters for required_key with String type.
+//!     ///
+//!     /// In the Activity Streams spec, 'functional' means there can only be one item for this
+//!     /// key. This means all fields not labeled 'functional' can also be serialized/deserialized
+//!     /// as Vec<T>.
+//!     #[activitystreams(concrete(String), functional)]
+//!     pub required_key: serde_json::Value,
+//! }
+//!
+//! fn run() -> Result<(), Error> {
+//!     let mut props = MyProperties::default();
+//!
+//!     props.set_required_key_string("Hey".to_owned())?;
+//!
+//!     let my_link = CustomLink::new(Mention::default(), props);
+//!
+//!     let my_link_string = serde_json::to_string(&my_link)?;
+//!
+//!     let my_link: CustomLink<Mention, MyProperties> = serde_json::from_str(&my_link_string)?;
+//!
+//!     Ok(())
+//! }
+//! # fn main() {
+//! #   run().unwrap();
+//! # }
+//! ```
+
 extern crate activitystreams_traits;
 extern crate activitystreams_types;
 
 pub mod activity;
 pub mod actor;
 pub mod collection;
-pub mod error;
+mod error;
 pub mod link;
 pub mod object;
 pub mod properties;
@@ -31,6 +152,7 @@ pub mod properties;
 pub use self::activity::{Activity, IntransitiveActivity};
 pub use self::actor::Actor;
 pub use self::collection::{Collection, CollectionPage};
-pub use self::error::Error;
+pub use self::error::{Error, Result};
 pub use self::link::Link;
 pub use self::object::Object;
+pub use activitystreams_types::context;

src/link.rs

@@ -17,5 +17,16 @@
  * along with ActivityStreams.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+//! Link traits and types
+
+/// A Link is an indirect, qualified reference to a resource identified by a URL.
+///
+/// The fundamental model for links is established by
+/// [[RFC5988](https://tools.ietf.org/html/rfc5988)]. Many of the properties defined by the
+/// Activity Vocabulary allow values that are either instances of Object or Link. When a Link is
+/// used, it establishes a qualified relation connecting the subject (the containing object) to the
+/// resource identified by the href. Properties of the Link are properties of the reference as
+/// opposed to properties of the resource.
 pub use activitystreams_traits::Link;
+
 pub use activitystreams_types::link::*;

src/object.rs

@@ -17,5 +17,13 @@
  * along with ActivityStreams.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+//! Object traits and types
+
+/// Describes an object of any kind.
+///
+/// The Object type serves as the base type for most of the other kinds of objects defined in the
+/// Activity Vocabulary, including other Core types such as `Activity`, `IntransitiveActivity`,
+/// `Collection` and `OrderedCollection`.
 pub use activitystreams_traits::Object;
+
 pub use activitystreams_types::object::*;

src/properties.rs

@@ -17,4 +17,6 @@
  * along with ActivityStreams.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+//! Helpers for translating properties between `serde_json::Value` and concrete types
+
 pub use activitystreams_traits::properties::*;