Document traits

activitystreams-derive/README.md

@@ -64,8 +64,8 @@ Feel free to open issues for anything you find an issue with. Please note that a
 
 Copyright © 2018 Riley Trautman
 
-Tokio ZMQ 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 Derive 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.
 
-Tokio ZMQ 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 Tokio ZMQ.
+ActivityStreams Derive 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 Derive.
 
-You should have received a copy of the GNU General Public License along with Tokio ZMQ. If not, see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).
+You should have received a copy of the GNU General Public License along with ActivityStreams Derive. If not, see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).

activitystreams-traits/Cargo.toml

@@ -5,6 +5,7 @@ version = "0.1.0"
 license = "GPL-3.0"
 authors = ["asonix <asonix.dev@gmail.com>"]
 repository = "https://github.com/asonix/activitystreams"
+readme = "README.md"
 keywords = ["activitystreams", "activitypub"]
 
 [dependencies]

activitystreams-traits/README.md

@@ -0,0 +1,39 @@
+# ActivityStreams Traits
+__Traits for Activity Streams__
+
+These traits don't provide any functionality other than anotations for types created in other
+projects. See the `activitystreams-types` crate for examples of how these traits could be used.
+
+## Examples
+
+```rust
+extern crate activitystreams_traits;
+extern crate serde;
+#[macro_use]
+extern crate serde_derive;
+
+use activitystreams_traits::{Object, Actor};
+
+#[derive(Clone, Debug, Default, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Persona {
+    #[serde(rename = "type")]
+    kind: String,
+}
+
+impl Object for Persona {}
+impl Actor for Persona {}
+```
+
+## 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 Traits 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 Traits 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 Traits.
+
+You should have received a copy of the GNU General Public License along with ActivityStreams Traits. If not, see [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).

activitystreams-traits/src/activity.rs

@@ -19,5 +19,16 @@
 
 use object::Object;
 
+/// 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 trait Activity: Object {}
+
+/// Instances of `IntransitiveActivity` are a subtype of `Activity` representing intransitive
+/// actions.
+///
+/// The `object` property is therefore inappropriate for these activities.
 pub trait IntransitiveActivity: Activity {}

activitystreams-traits/src/collection.rs

@@ -21,7 +21,23 @@ use object::Object;
 
 /// 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 trait Collection: Object {}
 
 /// 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 trait CollectionPage: Collection {}

activitystreams-traits/src/lib.rs

@@ -17,6 +17,32 @@
  * along with ActivityStreams Traits.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+//! Traits for Activity Streams
+//!
+//! These traits don't provide any functionality other than anotations for types created in other
+//! projects. See the `activitystreams-types` crate for examples of how these traits could be used.
+//!
+//! ## Examples
+//!
+//! ```rust
+//! extern crate activitystreams_traits;
+//! extern crate serde;
+//! #[macro_use]
+//! extern crate serde_derive;
+//!
+//! use activitystreams_traits::{Object, Actor};
+//!
+//! #[derive(Clone, Debug, Default, Deserialize, Serialize)]
+//! #[serde(rename_all = "camelCase")]
+//! pub struct Persona {
+//!     #[serde(rename = "type")]
+//!     kind: String,
+//! }
+//!
+//! impl Object for Persona {}
+//! impl Actor for Persona {}
+//! ```
+
 #[macro_use]
 extern crate failure;
 extern crate serde;

activitystreams-traits/src/link.rs

@@ -19,5 +19,12 @@
 
 use serde::{de::DeserializeOwned, ser::Serialize};
 
-/// The Link is the secondary base type for the Activity Streams vocabulary.
+/// 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 trait Link: DeserializeOwned + Serialize {}

activitystreams-traits/src/object.rs

@@ -19,5 +19,9 @@
 
 use serde::{de::DeserializeOwned, ser::Serialize};
 
-/// The Object is the primary base type for the Activity Streams vocabulary.
+/// 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 trait Object: DeserializeOwned + Serialize {}