Adding a lot of comments from ActivityPub/ActivityStreams/ActivityVocabulary specs

To quiet some go lint warnings

src/activitypub/actors.go

@@ -17,7 +17,10 @@ var validActorTypes = [...]ActivityVocabularyType{
 	ServiceType,
 }
 
-// Endpoints
+// Endpoints 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.
 type Endpoints struct {
 	// Upload endpoint URI for this user for binary data.
 	UploadMedia ObjectOrLink `jsonld:"uploadMedia,omitempty"`
@@ -41,7 +44,10 @@ type Endpoints struct {
 	SharedInbox ObjectOrLink `jsonld:"sharedInbox,omitempty"`
 }
 
-// Actor types are apObject types that are capable of performing activities.
+// Actor is generally one of the ActivityStreams Actor Types, but they don't have to be.
+// For example, a Profile object might be used as an actor, or a type from an ActivityStreams extension.
+// Actors are retrieved like any other Object in ActivityPub.
+// Like other ActivityStreams objects, actors have an id, which is a URI.
 type Actor struct {
 	*apObject
 	// A reference to an [ActivityStreams] OrderedCollection comprised of all the messages received by the actor;

src/activitypub/collections.go

@@ -2,10 +2,10 @@ package activitypub
 
 var validCollectionTypes = [...]ActivityVocabularyType{CollectionType, OrderedCollectionType}
 
-// Page
+// Page represents a Web Page.
 type Page ObjectOrLink
 
-// Collection
+// Collection is a subtype of Object that represents ordered or unordered sets of Object or Link instances.
 type Collection struct {
 	*apObject
 	// A non-negative integer specifying the total number of objects contained by the logical view of the collection.
@@ -15,7 +15,8 @@ type Collection struct {
 	Items ItemCollection `jsonld:"items,omitempty"`
 }
 
-// OrderedCollection
+// OrderedCollection is a subtype of Collection in which members of the logical
+// collection are assumed to always be strictly ordered.
 type OrderedCollection struct {
 	*apObject
 	// A non-negative integer specifying the total number of objects contained by the logical view of the collection.
@@ -25,7 +26,9 @@ type OrderedCollection struct {
 	OrderedItems ItemCollection `jsonld:"orderedItems,omitempty"`
 }
 
-// CollectionPage
+// CollectionPage is a Collection that contains a large number of items and when it becomes impractical
+// for an implementation to serialize every item contained by a Collection using the items (or orderedItems)
+// property alone. In such cases, the items within a Collection can be divided into distinct subsets or "pages".
 type CollectionPage struct {
 	PartOf *Collection
 	// In a paged Collection, indicates the page that contains the most recently updated member items.
@@ -40,7 +43,10 @@ type CollectionPage struct {
 	Prev Page `jsonld:"prev,omitempty"`
 }
 
-// OrderedCollectionPage
+// OrderedCollectionPage type extends from both CollectionPage and OrderedCollection.
+// In addition to the properties inherited from each of those, the OrderedCollectionPage
+// may contain an additional startIndex property whose value indicates the relative index position
+// of the first item contained by the page within the OrderedCollection to which the page belongs.
 type OrderedCollectionPage struct {
 	PartOf *OrderedCollection
 	// In a paged Collection, indicates the page that contains the most recently updated member items.

src/activitypub/following.go

@@ -1,9 +1,11 @@
 package activitypub
 
 type (
-	// FollowingCollection
+	// FollowingCollection is a list of everybody that the actor has followed, added as a side effect.
+	// The following collection MUST be either an OrderedCollection or a Collection and MAY
+	// be filtered on privileges of an authenticated user or as appropriate when no authentication is given.
 	FollowingCollection Following
 
-	// Following
+	// Following is a type alias for a simple Collection
 	Following Collection
 )

src/activitypub/inbox.go

@@ -1,9 +1,13 @@
 package activitypub
 
 type (
-	// InboxStream
+	// InboxStream contains all activities received by the actor.
+	// The server SHOULD filter content according to the requester's permission.
+	// In general, the owner of an inbox is likely to be able to access all of their inbox contents.
+	// Depending on access control, some other content may be public, whereas other content may
+	// require authentication for non-owner users, if they can access the inbox at all.
 	InboxStream Inbox
 
-	// Inbox
+	// Inbox is a type alias for an Ordered Collection
 	Inbox OrderedCollection
 )

src/activitypub/liked.go

@@ -1,9 +1,12 @@
 package activitypub
 
 type (
-	// LikedCollection
+	// LikedCollection is a list of every object from all of the actor's Like activities,
+	// added as a side effect. The liked collection MUST be either an OrderedCollection or
+	// a Collection and MAY be filtered on privileges of an authenticated user or as
+	// appropriate when no authentication is given.
 	LikedCollection Liked
 
-	// Liked
+	// Liked is a type alias for an Ordered Collection
 	Liked OrderedCollection
 )

src/activitypub/likes.go

@@ -1,9 +1,12 @@
 package activitypub
 
 type (
-	// LikesCollection
+	// LikesCollection is a list of all Like activities with this object as the object property,
+	// added as a side effect. The likes collection MUST be either an OrderedCollection or a Collection
+	// and MAY be filtered on privileges of an authenticated user or as appropriate when
+	// no authentication is given.
 	LikesCollection Likes
 
-	// Likes
+	// Likes is a type alias for an Ordered Collection
 	Likes OrderedCollection
 )

src/activitypub/link.go

@@ -40,7 +40,7 @@ type Link struct {
 	HrefLang LangRef `jsonld:"hrefLang,omitempty"`
 }
 
-// Mention
+// Mention is a specialized Link that represents an @mention.
 type Mention Link
 
 // ValidLinkType validates a type against the valid link types

src/activitypub/object.go

@@ -5,13 +5,24 @@ import (
 	"time"
 )
 
-// ObjectID
+// ObjectID designates an unique global identifier.
+// All Objects in [ActivityStreams] should have unique global identifiers.
+// ActivityPub extends this requirement; all objects distributed by the ActivityPub protocol MUST
+// have unique global identifiers, unless they are intentionally transient
+// (short lived activities that are not intended to be able to be looked up,
+// such as some kinds of chat messages or game notifications).
+// These identifiers must fall into one of the following groups:
+//
+// 1. Publicly dereferencable URIs, such as HTTPS URIs, with their authority belonging
+// to that of their originating server. (Publicly facing content SHOULD use HTTPS URIs).
+// 2. An ID explicitly specified as the JSON null object, which implies an anonymous object
+// (a part of its parent context)
 type ObjectID string
 
 const (
 	// ActivityBaseURI the basic URI for the activity streams namespaces
 	ActivityBaseURI          URI                    = URI("https://www.w3.org/ns/activitystreams#")
-	ObjectType               ActivityVocabularyType = "apObject"
+	ObjectType               ActivityVocabularyType = "ActivityPubObject"
 	LinkType                 ActivityVocabularyType = "Link"
 	ActivityType             ActivityVocabularyType = "Activity"
 	IntransitiveActivityType ActivityVocabularyType = "IntransitiveActivity"
@@ -19,7 +30,7 @@ const (
 	CollectionType           ActivityVocabularyType = "Collection"
 	OrderedCollectionType    ActivityVocabularyType = "OrderedCollection"
 
-	// apObject Types
+	// Activity Pub Object Types
 	ArticleType      ActivityVocabularyType = "Article"
 	AudioType        ActivityVocabularyType = "Audio"
 	DocumentType     ActivityVocabularyType = "Document"
@@ -33,7 +44,7 @@ const (
 	TombstoneType    ActivityVocabularyType = "Tombstone"
 	VideoType        ActivityVocabularyType = "Video"
 
-	// Link Types
+	// MentionType is a link type for @mentions
 	MentionType ActivityVocabularyType = "Mention"
 )
 
@@ -68,33 +79,35 @@ var validObjectTypes = [...]ActivityVocabularyType{
 }
 
 type (
-	// ActivityVocabularyType
+	// ActivityVocabularyType is the data type for an Activity type object
 	ActivityVocabularyType string
-	// ActivityObject
+	// ActivityObject is a subtype of Object that describes some form of action that may happen,
+	//  is currently happening, or has already happened
 	ActivityObject interface{}
-	// ObjectOrLink
+	// ObjectOrLink describes an object of any kind.
 	ObjectOrLink interface {
 		IsLink() bool
 		IsObject() bool
 	}
-	// LinkOrUri
+	// LinkOrUri is an interface that Object and Link structs implement, and at the same time
+	// they are kept disjointed
 	LinkOrUri interface{}
-	// ImageOrLink
+	// ImageOrLink is an interface that Image and Link structs implement
 	ImageOrLink interface{}
-	// MimeType
+	// MimeType is the type for MIME types
 	MimeType string
-	// LangRef
+	// LangRef is the type for a language reference, should be ISO 639-1 language specifier.
 	LangRef string
-	// NaturalLanguageValue
+	// NaturalLanguageValue is a mapping for multiple language values
 	NaturalLanguageValue map[LangRef]string
 )
 
-// IsLink validates if current apObject is a Link
+// IsLink validates if current Activity Pub Object is a Link
 func (o apObject) IsLink() bool {
 	return ValidLinkType(o.Type)
 }
 
-// IsObject validates if current apObject is an Object
+// IsObject validates if current Activity Pub Object is an Object
 func (o apObject) IsObject() bool {
 	return ValidObjectType(o.Type)
 }
@@ -193,10 +206,11 @@ type apObject struct {
 	Duration time.Duration `jsonld:"duration,omitempty"`
 }
 
-// ContentType
+// ContentType represents the content type for a Source object
 type ContentType string
 
-// Source
+// Source is intended to convey some sort of source from which the content markup was derived,
+// as a form of provenance, or to support future editing by clients.
 type Source struct {
 	Content   ContentType
 	MediaType string

src/activitypub/outbox.go

@@ -1,9 +1,11 @@
 package activitypub
 
 type (
-	// OutboxStream
+	// OutboxStream contains activities the user has published,
+	// subject to the ability of the requestor to retrieve the activity (that is,
+	// the contents of the outbox are filtered by the permissions of the person reading it).
 	OutboxStream Outbox
 
-	// Outbox
+	// Outbox is a type alias for an Ordered Collection
 	Outbox OrderedCollection
 )

src/activitypub/shares.go

@@ -1,9 +1,12 @@
 package activitypub
 
 type (
-	// SharesCollection
+	// SharesCollection is a list of all Announce activities with this object as the object property,
+	// added as a side effect. The shares collection MUST be either an OrderedCollection or a Collection
+	// and MAY be filtered on privileges of an authenticated user or as appropriate when no authentication
+	// is given.
 	SharesCollection Shares
 
-	// Shares
+	// Shares is a type alias for an Ordered Collection
 	Shares OrderedCollection
 )

src/activitypub/uri.go

@@ -1,9 +1,9 @@
 package activitypub
 
 type (
-	// IRI
+	// IRI is a Internationalized Resource Identifiers (IRIs) RFC3987
 	IRI URI
 
-	// URI
+	// URI is a Uniform Resource Identifier (URI) RFC3986
 	URI string
 )

src/jsonld/context.go

@@ -17,6 +17,7 @@ type Context struct {
 	Language activitypub.NaturalLanguageValue `jsonld:"@language,omitempty,collapsible"`
 }
 
+// Collapsible is an interface used by the JSON-LD marshaller to collapse a struct to one single value
 type Collapsible interface {
 	Collapse() []byte
 }
@@ -26,6 +27,7 @@ func (c *Context) Ref() Ref {
 	return Ref(c.URL)
 }
 
+// Collapse returns the plain text collapsed value of the current Context object
 func (c *Context) Collapse() []byte {
 	return []byte(c.URL)
 }

tests/integration_test.go

@@ -42,9 +42,9 @@ func TestCreateActivityHTTPSerialization(t *testing.T) {
 	obj := activitypub.AcceptNew(id, nil)
 	obj.Name["en"] = "Accept New"
 
-	baseUri := string(activitypub.ActivityBaseURI)
+	baseURI := string(activitypub.ActivityBaseURI)
 	ctx := jsonld.Context{
-		URL: jsonld.Ref(baseUri + string(obj.Type)),
+		URL: jsonld.Ref(baseURI + string(obj.Type)),
 	}
 	data, err := jsonld.Marshal(obj, &ctx)
 	if err != nil {