docs(apb): docstrings for methods

This commit is contained in:
əlemi 2024-06-10 03:10:44 +02:00
parent 8d42734e77
commit 58daf13708
Signed by: alemi
GPG key ID: A4895B84D311642C
4 changed files with 71 additions and 1 deletions

View file

@ -74,11 +74,24 @@ crate::strenum! {
pub trait Activity : Object {
fn activity_type(&self) -> Field<ActivityType> { Err(FieldErr("type")) }
/// 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.
fn actor(&self) -> Node<Self::Actor> { Node::Empty }
/// 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.
fn object(&self) -> Node<Self::Object> { Node::Empty }
/// 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.
fn target(&self) -> Node<Self::Object> { Node::Empty }
/// 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.
fn result(&self) -> Node<Self::Object> { Node::Empty }
/// 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".
fn origin(&self) -> Node<Self::Object> { Node::Empty }
/// Identifies one or more objects used (or to be used) in the completion of an Activity.
fn instrument(&self) -> Node<Self::Object> { Node::Empty }
}

View file

@ -15,15 +15,24 @@ pub trait Actor : Object {
type Endpoints : Endpoints;
fn actor_type(&self) -> Field<ActorType> { Err(FieldErr("type")) }
/// A short username which may be used to refer to the actor, with no uniqueness guarantees.
fn preferred_username(&self) -> Field<&str> { Err(FieldErr("preferredUsername")) }
/// A reference to an [ActivityStreams] OrderedCollection comprised of all the messages received by the actor; see 5.2 Inbox.
fn inbox(&self) -> Node<Self::Collection>;
/// An [ActivityStreams] OrderedCollection comprised of all the messages produced by the actor; see 5.1 Outbox.
fn outbox(&self) -> Node<Self::Collection>;
/// A link to an [ActivityStreams] collection of the actors that this actor is following; see 5.4 Following Collection
fn following(&self) -> Node<Self::Collection> { Node::Empty }
/// A link to an [ActivityStreams] collection of the actors that follow this actor; see 5.3 Followers Collection.
fn followers(&self) -> Node<Self::Collection> { Node::Empty }
/// A link to an [ActivityStreams] collection of objects this actor has liked; see 5.5 Liked Collection.
fn liked(&self) -> Node<Self::Collection> { Node::Empty }
/// A list of supplementary Collections which may be of interest.
fn streams(&self) -> Node<Self::Collection> { Node::Empty }
/// A json object which maps additional (typically server/domain-wide) endpoints which may be useful either for this actor or someone referencing this actor.
/// This mapping may be nested inside the actor document as the value or may be a link to a JSON-LD document with these properties.
fn endpoints(&self) -> Node<Self::Endpoints> { Node::Empty }
fn public_key(&self) -> Node<Self::PublicKey> { Node::Empty }
fn public_key(&self) -> Node<Self::PublicKey> { Node::Empty } // TODO hmmm where is this from??
#[cfg(feature = "activitypub-miscellaneous-terms")]
fn moved_to(&self) -> Node<Self::Actor> { Node::Empty }

View file

@ -17,11 +17,18 @@ pub trait Collection : Object {
fn collection_type(&self) -> Field<CollectionType> { Err(FieldErr("type")) }
/// A non-negative integer specifying the total number of objects contained by the logical view of the collection.
/// This number might not reflect the actual number of items serialized within the Collection object instance.
fn total_items(&self) -> Field<u64> { Err(FieldErr("totalItems")) }
/// In a paged Collection, indicates the page that contains the most recently updated member items.
fn current(&self) -> Node<Self::CollectionPage> { Node::Empty }
/// In a paged Collection, indicates the furthest preceeding page of items in the collection.
fn first(&self) -> Node<Self::CollectionPage> { Node::Empty }
/// In a paged Collection, indicates the furthest proceeding page of the collection.
fn last(&self) -> Node<Self::CollectionPage> { Node::Empty }
/// Identifies the items contained in a collection. The items might be ordered or unordered.
fn items(&self) -> Node<Self::Object> { Node::Empty }
/// ??????????????? same as items but ordered?? spec just uses it without saying
fn ordered_items(&self) -> Node<Self::Object> { Node::Empty }
}

View file

@ -41,33 +41,74 @@ pub trait Object : Base {
type Activity : crate::Activity;
fn object_type(&self) -> Field<ObjectType> { Err(FieldErr("type")) }
/// Identifies a resource attached or related to an object that potentially requires special handling
/// The intent is to provide a model that is at least semantically similar to attachments in email.
fn attachment(&self) -> Node<Self::Object> { Node::Empty }
/// Identifies one or more entities to which this object is attributed.
/// The attributed entities might not be Actors. For instance, an object might be attributed to the completion of another activity.
fn attributed_to(&self) -> Node<Self::Actor> { Node::Empty }
/// Identifies one or more entities that represent the total population of entities for which the object can considered to be relevant
fn audience(&self) -> Node<Self::Object> { Node::Empty }
/// The content or textual representation of the Object encoded as a JSON string. By default, the value of content is HTML
/// The mediaType property can be used in the object to indicate a different content type
/// The content MAY be expressed using multiple language-tagged values
fn content(&self) -> Field<&str> { Err(FieldErr("content")) } // TODO handle language maps
/// 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
fn context(&self) -> Node<Self::Object> { Node::Empty }
/// A simple, human-readable, plain-text name for the object. HTML markup MUST NOT be included. The name MAY be expressed using multiple language-tagged values
fn name(&self) -> Field<&str> { Err(FieldErr("name")) } // also in link // TODO handle language maps
/// The date and time describing the actual or expected ending time of the object
/// When used with an Activity object, for instance, the endTime property specifies the moment the activity concluded or is expected to conclude.
fn end_time(&self) -> Field<chrono::DateTime<chrono::Utc>> { Err(FieldErr("endTime")) }
/// Identifies the entity (e.g. an application) that generated the object
fn generator(&self) -> Node<Self::Actor> { Node::Empty }
/// Indicates an entity that describes an icon for this object
/// The image should have an aspect ratio of one (horizontal) to one (vertical) and should be suitable for presentation at a small size
fn icon(&self) -> Node<Self::Document> { Node::Empty }
/// Indicates an entity that describes an image for this object
/// Unlike the icon property, there are no aspect ratio or display size limitations assumed
fn image(&self) -> Node<Self::Document> { Node::Empty }
/// Indicates one or more entities for which this object is considered a response
fn in_reply_to(&self) -> Node<Self::Object> { Node::Empty }
/// Indicates one or more physical or logical locations associated with the object
fn location(&self) -> Node<Self::Object> { Node::Empty }
/// Identifies an entity that provides a preview of this object
fn preview(&self) -> Node<Self::Object> { Node::Empty } // also in link
/// The date and time at which the object was published
fn published(&self) -> Field<chrono::DateTime<chrono::Utc>> { Err(FieldErr("published")) }
/// The date and time at which the object was updated
fn updated(&self) -> Field<chrono::DateTime<chrono::Utc>> { Err(FieldErr("updated")) }
/// Identifies a Collection containing objects considered to be responses to this object
fn replies(&self) -> Node<Self::Collection> { Node::Empty }
fn likes(&self) -> Node<Self::Collection> { Node::Empty }
fn shares(&self) -> Node<Self::Collection> { Node::Empty }
/// The date and time describing the actual or expected starting time of the object.
/// When used with an Activity object, for instance, the startTime property specifies the moment the activity began or is scheduled to begin.
fn start_time(&self) -> Field<chrono::DateTime<chrono::Utc>> { Err(FieldErr("startTime")) }
/// A natural language summarization of the object encoded as HTML. Multiple language tagged summaries MAY be provided
fn summary(&self) -> Field<&str> { Err(FieldErr("summary")) }
/// One or more "tags" that have been associated with an objects. A tag can be any kind of Object
/// The key difference between attachment and tag is that the former implies association by inclusion, while the latter implies associated by reference
fn tag(&self) -> Node<Self::Object> { Node::Empty }
/// Identifies one or more links to representations of the object
fn url(&self) -> Node<Self::Link> { Node::Empty }
/// Identifies an entity considered to be part of the public primary audience of an Object
fn to(&self) -> Node<Self::Link> { Node::Empty }
/// Identifies an Object that is part of the private primary audience of this Object
fn bto(&self) -> Node<Self::Link> { Node::Empty }
/// Identifies an Object that is part of the public secondary audience of this Object
fn cc(&self) -> Node<Self::Link> { Node::Empty }
/// Identifies one or more Objects that are part of the private secondary audience of this Object
fn bcc(&self) -> Node<Self::Link> { Node::Empty }
/// When used on a Link, identifies the MIME media type of the referenced resource.
/// When used on an Object, identifies the MIME media type of the value of the content property.
/// If not specified, the content property is assumed to contain text/html content.
fn media_type(&self) -> Field<&str> { Err(FieldErr("mediaType")) } // also in link
/// When the object describes a time-bound resource, such as an audio or video, a meeting, etc, the duration property indicates the object's approximate duration.
/// The value MUST be expressed as an xsd:duration as defined by [ xmlschema11-2], section 3.3.6 (e.g. a period of 5 seconds is represented as "PT5S").
fn duration(&self) -> Field<&str> { Err(FieldErr("duration")) } // TODO how to parse xsd:duration ?
#[cfg(feature = "activitypub-miscellaneous-terms")]