From bb3112fb107414b7f59f9540443405216d7e3c75 Mon Sep 17 00:00:00 2001 From: asonix Date: Sun, 13 May 2018 23:22:34 -0500 Subject: [PATCH] Document traits --- activitystreams-derive/README.md | 6 ++-- activitystreams-traits/Cargo.toml | 1 + activitystreams-traits/README.md | 39 ++++++++++++++++++++++++ activitystreams-traits/src/activity.rs | 11 +++++++ activitystreams-traits/src/collection.rs | 16 ++++++++++ activitystreams-traits/src/lib.rs | 26 ++++++++++++++++ activitystreams-traits/src/link.rs | 9 +++++- activitystreams-traits/src/object.rs | 6 +++- 8 files changed, 109 insertions(+), 5 deletions(-) create mode 100644 activitystreams-traits/README.md diff --git a/activitystreams-derive/README.md b/activitystreams-derive/README.md index 775d811..980e9d6 100644 --- a/activitystreams-derive/README.md +++ b/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/). diff --git a/activitystreams-traits/Cargo.toml b/activitystreams-traits/Cargo.toml index 195b0e0..b62f558 100644 --- a/activitystreams-traits/Cargo.toml +++ b/activitystreams-traits/Cargo.toml @@ -5,6 +5,7 @@ version = "0.1.0" license = "GPL-3.0" authors = ["asonix "] repository = "https://github.com/asonix/activitystreams" +readme = "README.md" keywords = ["activitystreams", "activitypub"] [dependencies] diff --git a/activitystreams-traits/README.md b/activitystreams-traits/README.md new file mode 100644 index 0000000..03d1d4b --- /dev/null +++ b/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/). diff --git a/activitystreams-traits/src/activity.rs b/activitystreams-traits/src/activity.rs index 6c96d8d..d2506f8 100644 --- a/activitystreams-traits/src/activity.rs +++ b/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 {} diff --git a/activitystreams-traits/src/collection.rs b/activitystreams-traits/src/collection.rs index f2cc372..6545703 100644 --- a/activitystreams-traits/src/collection.rs +++ b/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 {} diff --git a/activitystreams-traits/src/lib.rs b/activitystreams-traits/src/lib.rs index fde30b2..7aa67b2 100644 --- a/activitystreams-traits/src/lib.rs +++ b/activitystreams-traits/src/lib.rs @@ -17,6 +17,32 @@ * along with ActivityStreams Traits. If not, see . */ +//! 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; diff --git a/activitystreams-traits/src/link.rs b/activitystreams-traits/src/link.rs index 66a1446..23e6cee 100644 --- a/activitystreams-traits/src/link.rs +++ b/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 {} diff --git a/activitystreams-traits/src/object.rs b/activitystreams-traits/src/object.rs index d6eb5ef..958f1db 100644 --- a/activitystreams-traits/src/object.rs +++ b/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 {}