Magic method docs (#1307)

* Magic method docs Part I * Add missing function docs Part II * Update docs * Revert comment changes * Use correct class docs * adjust alignment * Update property type docs * Update property types in base_object --------- Co-authored-by: Matthias Pfefferle <pfefferle@users.noreply.github.com>
Automattic · Feb 13, 2025 · 114f27a · 114f27a
1 parent 66dbef9
commit 114f27a
Show file tree

Hide file tree

Showing 9 changed files with 84 additions and 134 deletions.
diff --git a/includes/activity/class-activity.php b/includes/activity/class-activity.php
@@ -20,6 +20,38 @@
  *
  * @see https://www.w3.org/TR/activitystreams-core/#activities
  * @see https://www.w3.org/TR/activitystreams-core/#intransitiveactivities
+ *
+ * @method string|array|null       get_actor()          Gets one or more entities that performed or are expected to perform the activity.
+ * @method string|null             get_id()             Gets the object's unique global identifier.
+ * @method string                  get_type()           Gets the type of the object.
+ * @method string|null             get_name()           Gets the natural language name of the object.
+ * @method string|null             get_url()            Gets the URL of the object.
+ * @method string|null             get_summary()        Gets the natural language summary of the object.
+ * @method string|null             get_published()      Gets the date and time the object was published in ISO 8601 format.
+ * @method string|null             get_updated()        Gets the date and time the object was updated in ISO 8601 format.
+ * @method string|null             get_attributed_to()  Gets the entity attributed as the original author.
+ * @method array|string|null       get_cc()             Gets the secondary recipients of the object.
+ * @method array|string|null       get_to()             Gets the primary recipients of the object.
+ * @method array|null              get_attachment()     Gets the attachment property of the object.
+ * @method array|null              get_icon()           Gets the icon property of the object.
+ * @method array|null              get_image()          Gets the image property of the object.
+ * @method Base_Object|string|null get_object()         Gets the direct object of the activity.
+ * @method array|string|null       get_in_reply_to()    Gets the objects this object is in reply to.
+ *
+ * @method Activity set_actor( string|array $actor )    Sets one or more entities that performed the activity.
+ * @method Activity set_id( string $id )                Sets the object's unique global identifier.
+ * @method Activity set_type( string $type )            Sets the type of the object.
+ * @method Activity set_name( string $name )            Sets the natural language name of the object.
+ * @method Activity set_url( string $url )              Sets the URL of the object.
+ * @method Activity set_summary( string $summary )      Sets the natural language summary of the object.
+ * @method Activity set_published( string $published )  Sets the date and time the object was published in ISO 8601 format.
+ * @method Activity set_updated( string $updated )      Sets the date and time the object was updated in ISO 8601 format.
+ * @method Activity set_attributed_to( string $attributed_to ) Sets the entity attributed as the original author.
+ * @method Activity set_cc( array|string $cc )          Sets the secondary recipients of the object.
+ * @method Activity set_to( array|string $to )          Sets the primary recipients of the object.
+ * @method Activity set_attachment( array $attachment ) Sets the attachment property of the object.
+ * @method Activity set_icon( array $icon )             Sets the icon property of the object.
+ * @method Activity set_image( array $image )           Sets the image property of the object.
  */
 class Activity extends Base_Object {
 	const JSON_LD_CONTEXT = array(
@@ -40,10 +72,7 @@ class Activity extends Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-object-term
 	 *
-	 * @var string
-	 *    | Base_Object
-	 *    | Link
-	 *    | null
+	 * @var string|Base_Object|null
 	 */
 	protected $object;
 
@@ -55,11 +84,7 @@ class Activity extends Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-actor
 	 *
-	 * @var string
-	 *    | \ActivityPhp\Type\Extended\AbstractActor
-	 *    | array<Actor>
-	 *    | array<Link>
-	 *    | Link
+	 * @var string|array
 	 */
 	protected $actor;
 
@@ -74,11 +99,7 @@ class Activity extends Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-target
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | array<ObjectType>
-	 *    | Link
-	 *    | array<Link>
+	 * @var string|array
 	 */
 	protected $target;
 
@@ -90,10 +111,7 @@ class Activity extends Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-result
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | null
+	 * @var string|Base_Object
 	 */
 	protected $result;
 
@@ -106,9 +124,6 @@ class Activity extends Base_Object {
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-replies
 	 *
 	 * @var array
-	 *    | ObjectType
-	 *    | Link
-	 *    | null
 	 */
 	protected $replies;
 
@@ -122,10 +137,7 @@ class Activity extends Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-origin
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | null
+	 * @var string|array
 	 */
 	protected $origin;
 
@@ -135,10 +147,7 @@ class Activity extends Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-instrument
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | null
+	 * @var string|array
 	 */
 	protected $instrument;
 
@@ -151,8 +160,6 @@ class Activity extends Base_Object {
 	 * @see https://www.w3.org/TR/activitypub/#object-without-create
 	 *
 	 * @param array|string|Base_Object|Link|null $data Activity object.
-	 *
-	 * @return void
 	 */
 	public function set_object( $data ) {
 		// Convert array to object.

diff --git a/includes/activity/class-actor.php b/includes/activity/class-actor.php
@@ -66,8 +66,7 @@ class Actor extends Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitypub/#inbox
 	 *
-	 * @var string
-	 *    | null
+	 * @var string|null
 	 */
 	protected $inbox;
 
@@ -77,8 +76,7 @@ class Actor extends Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitypub/#outbox
 	 *
-	 * @var string
-	 *    | null
+	 * @var string|null
 	 */
 	protected $outbox;
 

diff --git a/includes/activity/class-base-object.php b/includes/activity/class-base-object.php
@@ -61,12 +61,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-attachment
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | array<ObjectType>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|null
 	 */
 	protected $attachment;
 
@@ -77,12 +72,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-attributedto
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | array<ObjectType>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|null
 	 */
 	protected $attributed_to;
 
@@ -92,12 +82,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-audience
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | array<ObjectType>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|null
 	 */
 	protected $audience;
 
@@ -127,10 +112,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-context
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | null
+	 * @var string|null
 	 */
 	protected $context;
 
@@ -191,12 +173,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-icon
 	 *
-	 * @var string
-	 *    | Image
-	 *    | Link
-	 *    | array<Image>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|array|null
 	 */
 	protected $icon;
 
@@ -207,12 +184,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-image-term
 	 *
-	 * @var string
-	 *    | Image
-	 *    | Link
-	 *    | array<Image>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|array|null
 	 */
 	protected $image;
 
@@ -222,12 +194,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-inreplyto
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | array<ObjectType>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|null
 	 */
 	protected $in_reply_to;
 
@@ -237,12 +204,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-location
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | array<ObjectType>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|null
 	 */
 	protected $location;
 
@@ -251,10 +213,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-preview
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | null
+	 * @var string|null
 	 */
 	protected $preview;
 
@@ -286,10 +245,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-summary
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | null
+	 * @var string|null
 	 */
 	protected $summary;
 
@@ -299,7 +255,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-summary
 	 *
-	 * @var array<string>|null
+	 * @var string[]|null
 	 */
 	protected $summary_map;
 
@@ -312,12 +268,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-tag
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | array<ObjectType>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|null
 	 */
 	protected $tag;
 
@@ -333,11 +284,7 @@ class Base_Object {
 	/**
 	 * One or more links to representations of the object.
 	 *
-	 * @var string
-	 *    | array<string>
-	 *    | Link
-	 *    | array<Link>
-	 *    | null
+	 * @var string|null
 	 */
 	protected $url;
 
@@ -347,12 +294,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-to
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | array<ObjectType>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|array|null
 	 */
 	protected $to;
 
@@ -362,12 +304,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-bto
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | array<ObjectType>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|array|null
 	 */
 	protected $bto;
 
@@ -377,12 +314,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-cc
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | array<ObjectType>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|array|null
 	 */
 	protected $cc;
 
@@ -392,12 +324,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-bcc
 	 *
-	 * @var string
-	 *    | ObjectType
-	 *    | Link
-	 *    | array<ObjectType>
-	 *    | array<Link>
-	 *    | null
+	 * @var string|array|null
 	 */
 	protected $bcc;
 
@@ -443,10 +370,7 @@ class Base_Object {
 	 *
 	 * @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-replies
 	 *
-	 * @var string
-	 *    | Collection
-	 *    | Link
-	 *    | null
+	 * @var string|array|null
 	 */
 	protected $replies;