Make WordPress Core

Opened 6 weeks ago

Last modified 109 minutes ago

#61399 assigned enhancement

HTML API: Add type annotations

Reported by: jonsurrell's profile jonsurrell Owned by: jonsurrell's profile jonsurrell
Milestone: Future Release Priority: normal
Severity: normal Version:
Component: HTML API Keywords: has-patch has-unit-tests
Focuses: Cc:

Description

The HTML API benefits from adding type annotations where possible and supported. It makes development easier and helps to discover tricky bugs.

Change History (39)

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


6 weeks ago
#1

  • Keywords has-patch added

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, they can be landed independently and as bugfixes for WordPress 6.6.

Trac ticket: https://core.trac.wordpress.org/ticket/61399

This ticket was mentioned in PR #6754 on WordPress/wordpress-develop by @jonsurrell.


6 weeks ago
#2

This applies three fixes that appeared as part of adding type annotations to the HTML API in #6753.

  • Fix a bug where a string was passed instead of a token
  • Fix Tag Processor bug where null was used as int
  • Fix return type error in tag processor get_token_name

Trac ticket: https://core.trac.wordpress.org/ticket/61399

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

#3 @dmsnell
6 weeks ago

  • Milestone changed from Awaiting Review to 6.6

#4 @dmsnell
6 weeks ago

In 58364:

HTML API: Fix three small type-related bugs.

This applies three fixes that appeared as part of
adding type annotations to the HTML API.

Developed in https://github.com/WordPress/wordpress-develop/pull/6754
Discussed in https://core.trac.wordpress.org/ticket/61399

Props jonsurrell.
See #61399.
Follow-up to [55203], [56274].

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


6 weeks ago
#6

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


6 weeks ago
#7

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


5 weeks ago
#8

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

#9 @dmsnell
4 weeks ago

  • Milestone changed from 6.6 to Future Release

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


4 weeks ago
#10

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


4 weeks ago
#11

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


3 weeks ago
#12

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


3 weeks ago
#13

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


3 weeks ago
#14

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

#15 @jonsurrell
3 weeks ago

@dmsnell and I talked about this. @dmsnell shared concerns around this causing crashes on sites and wanting to be careful. These are valid.

We discussed introducing type annotations on places that should be safe, meaning that they can't introduce new crashes.

  • Private methods may be safe to annotate completely.
  • Return types should be safe to annotate.
  • Public method arguments are more risky to type and we'll avoid them for now. It's relatively easy to pass values of the wrong type and introduce runtime errors.

I'll adapt PR#6753 accordingly.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


5 days ago
#16

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


5 days ago
#17

  • Keywords has-unit-tests added

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


5 days ago
#18

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Closes https://github.com/WordPress/wordpress-develop/pull/7031 (supersedes)

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


5 days ago
#19

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


5 days ago
#20

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


5 days ago
#21

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


5 days ago
#22

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


5 days ago
#23

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


5 days ago
#24

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


5 days ago
#25

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

@jonsurrell commented on PR #6753:


5 days ago
#26

I've removed most of the type annotations from the parameters of public APIs. I did this to address concerns about the potential to break sites due to type errors from plugins that are not actionable in any way for the sites. I've maintained the type annotations on the private APIs and internal classes.

@dmsnell What do you think about the low-level API like the token map? Should I remove types in the same way there as well?

This ticket was mentioned in PR #7031 on WordPress/wordpress-develop by @jonsurrell.


5 days ago
#27

Trac ticket: Core-61399

#28 @dmsnell
3 days ago

In 58742:

Fix phpdoc nullable types in some files.

It was found that in several places in the HTML API and its supporting files,
the wrong form of type annotation was used for optional parameters.

Instead of using ?type, this patch uses type|type-of-default-value instead,
noting where important if the parameter is optional, and if so, what its default
value is.

Developed in https://github.com/WordPress/wordpress-develop/pull/7031
Discussed in https://core.trac.wordpress.org/ticket/61399

Props dmsnell, jonsurrell.
See #61399.

@dmsnell commented on PR #7031:


3 days ago
#29

Thank you, @sirreal. I updated the patch with some Optional. and Default declarations.

Merged in [58742]
https://github.com/wordpress/wordpress-develop/commit/48c0c968468b54ec2909317e1a9384c0943c0dd3

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


2 days ago
#30

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


2 days ago
#31

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

@dmsnell commented on PR #6753:


38 hours ago
#32

@sirreal I think all of this as is is probably fine, but I want to run this against the Gutenberg repository first to ensure that nothing basic is broken, since we're introducing new intentional-breaking behaviors.

@dmsnell commented on PR #6753:


36 hours ago
#33

Backport contains these anticipated updates in the following Gutenberg PR.

https://github.com/WordPress/gutenberg/pull/63723

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


13 hours ago
#34

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


13 hours ago
#35

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

#36 @dmsnell
12 hours ago

In 58769:

HTML API: Add PHP type annotations.

This patch adds type annotations to internal and private methods of the HTML
API and the supporting WP_Token_Map. Annotations have not been added to the
public interfaces where it would likely crash a site if called wrong.

These annotations should help avoid unnecessary type-related bugs (as have
been uncovered in earlier work adding such annotations) and provide additional
guidance to developers when interacting with these classes in an IDE.

Developed in https://github.com/WordPress/wordpress-develop/pull/6753
Discussed in https://core.trac.wordpress.org/ticket/61399

Props dmsnell, jonsurrell.
See #61399.

This ticket was mentioned in PR #6753 on WordPress/wordpress-develop by @jonsurrell.


12 hours ago
#38

Trac ticket: Core-61399

Add type annotations in the HTML API where possible. In this PR I've avoided adding annotations where the supported annotations are worse that PHPDoc annotations.

For example, I've avoided using the array type where the @param or @return annotations are more expressive, or a mixed type instead of a type union.

I've extracted some bugfixes that arose as part of this work to https://github.com/WordPress/wordpress-develop/pull/6754, that's a smaller patch that can be landed independently.

Includes https://github.com/WordPress/wordpress-develop/pull/7031.

@TobiasBg commented on PR #6753:


109 minutes ago
#39

@dmsnell @sirreal:
I see 2-3 $case_sensitivity parameters (2nd/3rd parameters of a function) that could also get a string annotation?
Or is this similar to $termination_list not getting array as the PHPDoc has the more specific string[] (which is intentional from what I understand from the PR description)?
I would actually vote for adding these as well, as the annotations not only serve documentation purposes but also prevent wrong parameter types from being passed to the function.

Note: See TracTickets for help on using tickets.