Skip to content

Commit a920b1d

Browse files
obenlandpfefferle
obenland
and
pfefferle
authored
Docs: Improve type hints (#1363)
* Docs: Improve type hints * Move magic method docs to Base_Object * Order alphabetically --------- Co-authored-by: Matthias Pfefferle <pfefferle@users.noreply.github.com>
1 parent d059750 commit a920b1d

17 files changed

+92
-79
lines changed

‎includes/activity/class-activity.php‎

Lines changed: 1 addition & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -20,39 +20,6 @@
2020
*
2121
* @see https://www.w3.org/TR/activitystreams-core/#activities
2222
* @see https://www.w3.org/TR/activitystreams-core/#intransitiveactivities
23-
*
24-
* @method string|array|null get_actor() Gets one or more entities that performed or are expected to perform the activity.
25-
* @method string|null get_id() Gets the object's unique global identifier.
26-
* @method string get_type() Gets the type of the object.
27-
* @method string|null get_name() Gets the natural language name of the object.
28-
* @method string|null get_url() Gets the URL of the object.
29-
* @method string|null get_summary() Gets the natural language summary of the object.
30-
* @method string|null get_published() Gets the date and time the object was published in ISO 8601 format.
31-
* @method string|null get_updated() Gets the date and time the object was updated in ISO 8601 format.
32-
* @method string|null get_attributed_to() Gets the entity attributed as the original author.
33-
* @method array|string|null get_cc() Gets the secondary recipients of the object.
34-
* @method array|string|null get_to() Gets the primary recipients of the object.
35-
* @method array|null get_attachment() Gets the attachment property of the object.
36-
* @method array|null get_icon() Gets the icon property of the object.
37-
* @method array|null get_image() Gets the image property of the object.
38-
* @method Base_Object|string|null get_object() Gets the direct object of the activity.
39-
* @method array|string|null get_in_reply_to() Gets the objects this object is in reply to.
40-
*
41-
* @method Activity set_actor( string|array $actor ) Sets one or more entities that performed the activity.
42-
* @method Activity set_id( string $id ) Sets the object's unique global identifier.
43-
* @method Activity set_type( string $type ) Sets the type of the object.
44-
* @method Activity set_name( string $name ) Sets the natural language name of the object.
45-
* @method Activity set_url( string $url ) Sets the URL of the object.
46-
* @method Activity set_summary( string $summary ) Sets the natural language summary of the object.
47-
* @method Activity set_published( string $published ) Sets the date and time the object was published in ISO 8601 format.
48-
* @method Activity set_updated( string $updated ) Sets the date and time the object was updated in ISO 8601 format.
49-
* @method Activity set_attributed_to( string $attributed_to ) Sets the entity attributed as the original author.
50-
* @method Activity set_cc( array|string $cc ) Sets the secondary recipients of the object.
51-
* @method Activity set_to( array|string $to ) Sets the primary recipients of the object.
52-
* @method Activity set_attachment( array $attachment ) Sets the attachment property of the object.
53-
* @method Activity set_icon( array $icon ) Sets the icon property of the object.
54-
* @method Activity set_image( array $image ) Sets the image property of the object.
55-
* @method Activity set_content( string $content ) Sets the content property of the object.
5623
*/
5724
class Activity extends Base_Object {
5825
const JSON_LD_CONTEXT = array(
@@ -156,7 +123,7 @@ class Activity extends Base_Object {
156123
* Set the object and copy Object properties to the Activity.
157124
*
158125
* Any to, bto, cc, bcc, and audience properties specified on the object
159-
* MUST be copied over to the new Create activity by the server.
126+
* MUST be copied over to the new "Create" activity by the server.
160127
*
161128
* @see https://www.w3.org/TR/activitypub/#object-without-create
162129
*

‎includes/activity/class-base-object.php‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,47 @@
2020
* 'Base_' for this reason.
2121
*
2222
* @see https://www.w3.org/TR/activitystreams-core/#object
23+
*
24+
* @method string|null get_actor() Gets one or more entities that performed or are expected to perform the activity.
25+
* @method string|null get_attributed_to() Gets the entity attributed as the original author.
26+
* @method array|null get_attachment() Gets the attachment property of the object.
27+
* @method string|null get_cc() Gets the secondary recipients of the object.
28+
* @method string|null get_content() Gets the content property of the object.
29+
* @method array|null get_icon() Gets the icon property of the object.
30+
* @method string|null get_id() Gets the object's unique global identifier.
31+
* @method array|null get_image() Gets the image property of the object.
32+
* @method array|string|null get_in_reply_to() Gets the objects this object is in reply to.
33+
* @method string|null get_name() Gets the natural language name of the object.
34+
* @method Base_Object|string|null get_object() Gets the direct object of the activity.
35+
* @method string|null get_published() Gets the date and time the object was published in ISO 8601 format.
36+
* @method string|null get_summary() Gets the natural language summary of the object.
37+
* @method array|null get_tag() Gets the tag property of the object.
38+
* @method array|string|null get_to() Gets the primary recipients of the object.
39+
* @method string get_type() Gets the type of the object.
40+
* @method string|null get_updated() Gets the date and time the object was updated in ISO 8601 format.
41+
* @method string|null get_url() Gets the URL of the object.
42+
*
43+
* @method string|array add_cc( string|array $cc ) Adds one or more entities to the secondary audience of the object.
44+
* @method string|array add_to( string|array $to ) Adds one or more entities to the primary audience of the object.
45+
*
46+
* @method Base_Object set_actor( string|array $actor ) Sets one or more entities that performed the activity.
47+
* @method Base_Object set_attachment( array $attachment ) Sets the attachment property of the object.
48+
* @method Base_Object set_attributed_to( string $attributed_to ) Sets the entity attributed as the original author.
49+
* @method Base_Object set_cc( array|string $cc ) Sets the secondary recipients of the object.
50+
* @method Base_Object set_content( string $content ) Sets the content property of the object.
51+
* @method Base_Object set_content_map( array $content_map ) Sets the content property of the object.
52+
* @method Base_Object set_icon( array $icon ) Sets the icon property of the object.
53+
* @method Base_Object set_id( string $id ) Sets the object's unique global identifier.
54+
* @method Base_Object set_image( array $image ) Sets the image property of the object.
55+
* @method Base_Object set_name( string $name ) Sets the natural language name of the object.
56+
* @method Base_Object set_published( string $published ) Sets the date and time the object was published in ISO 8601 format.
57+
* @method Base_Object set_sensitive( bool $sensitive ) Sets the sensitive property of the object.
58+
* @method Base_Object set_summary( string $summary ) Sets the natural language summary of the object.
59+
* @method Base_Object set_summary_map( array|null $summary_map ) Sets the summary property of the object.
60+
* @method Base_Object set_to( array|string $to ) Sets the primary recipients of the object.
61+
* @method Base_Object set_type( string $type ) Sets the type of the object.
62+
* @method Base_Object set_updated( string $updated ) Sets the date and time the object was updated in ISO 8601 format.
63+
* @method Base_Object set_url( string $url ) Sets the URL of the object.
2364
*/
2465
class Base_Object extends Generic_Object {
2566
/**

‎includes/activity/class-generic-object.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -175,7 +175,7 @@ public static function init_from_json( $json ) {
175175
*
176176
* @param array $data The object array.
177177
*
178-
* @return Base_Object|\WP_Error An Object built from the input array or WP_Error when it's not an array.
178+
* @return Generic_Object|\WP_Error An Object built from the input array or WP_Error when it's not an array.
179179
*/
180180
public static function init_from_array( $data ) {
181181
if ( ! is_array( $data ) ) {

‎includes/activity/extended-object/class-event.php‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ class Event extends Base_Object {
5050
);
5151

5252
/**
53-
* Mobilizon compatible values for repliesModertaionOption.
53+
* Mobilizon compatible values for repliesModerationOption.
5454
*
5555
* @var array
5656
*/
@@ -342,15 +342,15 @@ public function set_status( $status ) {
342342
/**
343343
* Custom setter for the event category.
344344
*
345-
* Falls back to Mobilizons default category.
345+
* Falls back to Mobilizon's default category.
346346
*
347-
* @param string $category The category of the event.
348-
* @param bool $mobilizon_compatibilty Optional. Whether the category must be compatibly with Mobilizon. Default true.
347+
* @param string $category The category of the event.
348+
* @param bool $mobilizon_compatibility Optional. Whether the category must be compatibly with Mobilizon. Default true.
349349
*
350350
* @return Event
351351
*/
352-
public function set_category( $category, $mobilizon_compatibilty = true ) {
353-
if ( $mobilizon_compatibilty ) {
352+
public function set_category( $category, $mobilizon_compatibility = true ) {
353+
if ( $mobilizon_compatibility ) {
354354
$this->category = in_array( $category, self::DEFAULT_EVENT_CATEGORIES, true ) ? $category : 'MEETING';
355355
} else {
356356
$this->category = $category;

‎includes/activity/extended-object/class-place.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,8 @@ class Place extends Base_Object {
3838
protected $accuracy;
3939

4040
/**
41-
* Indicates the altitude of a place. The measurement units is indicated using the units property.
42-
* If units is not specified, the default is assumed to be "m" indicating meters.
41+
* Indicates the altitude of a place. The measurement unit is indicated using the unit's property.
42+
* If unit is not specified, the default is assumed to be "m" indicating meters.
4343
*
4444
* @see https://www.w3.org/TR/activitystreams-vocabulary/#dfn-altitude
4545
* @var float xsd:float

‎includes/class-activitypub.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -264,7 +264,7 @@ public static function template_redirect() {
264264

265265
$comment = get_comment( $comment_id );
266266

267-
// Load a 404 page if `c` is set but not valid.
267+
// Load a 404-page if `c` is set but not valid.
268268
if ( ! $comment ) {
269269
global $wp_query;
270270
$wp_query->set_404();

‎includes/class-query.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -190,8 +190,8 @@ public function get_queried_object() {
190190
* Virtual objects are objects that are not stored in the database, but are created on the fly.
191191
* The plugins currently supports two virtual objects: The Blog-Actor and the Application-Actor.
192192
*
193-
* @see \Activitypub\Blog
194-
* @see \Activitypub\Application
193+
* @see \Activitypub\Model\Blog
194+
* @see \Activitypub\Model\Application
195195
*
196196
* @return object|null The virtual object.
197197
*/

‎includes/class-scheduler.php‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@
1414
use Activitypub\Collection\Outbox;
1515
use Activitypub\Collection\Followers;
1616
use Activitypub\Transformer\Factory;
17+
1718
/**
1819
* Scheduler class.
1920
*
@@ -389,10 +390,10 @@ private static function next_scheduled_hook( $hook ) {
389390
/**
390391
* Send announces.
391392
*
392-
* @param int $outbox_activity_id The outbox activity ID.
393-
* @param Activity $activity_object The activity object.
394-
* @param int $actor_id The actor ID.
395-
* @param int $content_visibility The content visibility.
393+
* @param int $outbox_activity_id The outbox activity ID.
394+
* @param \Activitypub\Activity\Activity $activity_object The activity object.
395+
* @param int $actor_id The actor ID.
396+
* @param int $content_visibility The content visibility.
396397
*/
397398
public static function schedule_announce_activity( $outbox_activity_id, $activity_object, $actor_id, $content_visibility ) {
398399
// Only if we're in both Blog and User modes.

‎includes/collection/class-followers.php‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -83,9 +83,9 @@ public static function remove_follower( $user_id, $actor ) {
8383
/**
8484
* Fires before a Follower is removed.
8585
*
86-
* @param \Activitypub\Model\Follower $follower The Follower object.
87-
* @param int $user_id The ID of the WordPress User.
88-
* @param string $actor The Actor URL.
86+
* @param Follower $follower The Follower object.
87+
* @param int $user_id The ID of the WordPress User.
88+
* @param string $actor The Actor URL.
8989
*/
9090
do_action( 'activitypub_followers_pre_remove_follower', $follower, $user_id, $actor );
9191

@@ -98,7 +98,7 @@ public static function remove_follower( $user_id, $actor ) {
9898
* @param int $user_id The ID of the WordPress User.
9999
* @param string $actor The Actor URL.
100100
*
101-
* @return \Activitypub\Activity\Base_Object|WP_Error|null The Follower object or null
101+
* @return Follower|false|null The Follower object or null
102102
*/
103103
public static function get_follower( $user_id, $actor ) {
104104
global $wpdb;
@@ -128,7 +128,7 @@ public static function get_follower( $user_id, $actor ) {
128128
*
129129
* @param string $actor The Actor URL.
130130
*
131-
* @return \Activitypub\Activity\Base_Object|WP_Error|null
131+
* @return Follower|false|null The Follower object or false on failure.
132132
*/
133133
public static function get_follower_by_actor( $actor ) {
134134
global $wpdb;
@@ -156,7 +156,7 @@ public static function get_follower_by_actor( $actor ) {
156156
* @param int $number Maximum number of results to return.
157157
* @param int $page Page number.
158158
* @param array $args The WP_Query arguments.
159-
* @return array List of `Follower` objects.
159+
* @return Follower[] List of `Follower` objects.
160160
*/
161161
public static function get_followers( $user_id, $number = -1, $page = null, $args = array() ) {
162162
$data = self::get_followers_with_count( $user_id, $number, $page, $args );
@@ -174,8 +174,8 @@ public static function get_followers( $user_id, $number = -1, $page = null, $arg
174174
* @return array {
175175
* Data about the followers.
176176
*
177-
* @type array $followers List of `Follower` objects.
178-
* @type int $total Total number of followers.
177+
* @type Follower[] $followers List of `Follower` objects.
178+
* @type int $total Total number of followers.
179179
* }
180180
*/
181181
public static function get_followers_with_count( $user_id, $number = -1, $page = null, $args = array() ) {
@@ -206,7 +206,7 @@ public static function get_followers_with_count( $user_id, $number = -1, $page =
206206
/**
207207
* Get all Followers.
208208
*
209-
* @return array The Term list of Followers.
209+
* @return Follower[] The Term list of Followers.
210210
*/
211211
public static function get_all_followers() {
212212
$args = array(
@@ -276,7 +276,7 @@ public static function get_inboxes( $user_id ) {
276276
return $inboxes;
277277
}
278278

279-
// Get all Followers of a ID of the WordPress User.
279+
// Get all Followers of an ID of the WordPress User.
280280
$posts = new WP_Query(
281281
array(
282282
'nopaging' => true,
@@ -368,7 +368,7 @@ public static function maybe_add_inboxes_of_blog_user( $json, $actor_id ) {
368368
}
369369

370370
$activity = json_decode( $json, true );
371-
// Only if this is an Update or Delete. Create handles its own Announce in dual user mode.
371+
// Only if this is an Update or Delete. Create handles its own "Announce" in dual user mode.
372372
if ( ! in_array( $activity['type'] ?? null, array( 'Update', 'Delete' ), true ) ) {
373373
return false;
374374
}
@@ -382,7 +382,7 @@ public static function maybe_add_inboxes_of_blog_user( $json, $actor_id ) {
382382
* @param int $number Optional. Limits the result. Default 50.
383383
* @param int $older_than Optional. The time in seconds. Default 86400 (1 day).
384384
*
385-
* @return array The Term list of Followers.
385+
* @return Follower[] The Term list of Followers.
386386
*/
387387
public static function get_outdated_followers( $number = 50, $older_than = 86400 ) {
388388
$args = array(
@@ -410,7 +410,7 @@ public static function get_outdated_followers( $number = 50, $older_than = 86400
410410
*
411411
* @param int $number Optional. The number of Followers to return. Default 20.
412412
*
413-
* @return array The Term list of Followers.
413+
* @return Follower[] The Term list of Followers.
414414
*/
415415
public static function get_faulty_followers( $number = 20 ) {
416416
$args = array(

‎includes/collection/class-outbox.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -256,7 +256,7 @@ public static function get_actor( $outbox_item ) {
256256
*
257257
* @param \WP_Post $outbox_item The Outbox post.
258258
*
259-
* @return \Activitypub\Activity\Activity|\WP_Error The Activity object or WP_Error.
259+
* @return Activity|\WP_Error The Activity object or WP_Error.
260260
*/
261261
public static function maybe_get_activity( $outbox_item ) {
262262
if ( ! $outbox_item || ! $outbox_item instanceof \WP_Post ) {

0 commit comments

Comments
 (0)