Skip to content

@experimental without inline notice is stripped from API docs members #20039

@pomek

Description

@pomek

📝 Provide detailed reproduction steps (if any)

  1. Add a class member with a plain @experimental annotation but without an inline Experimental: notice, for example:
    /**
     * Flag indicating whether a plugin is enabled or disabled.
     *
     * @experimental
     * @observable
     * @readonly
     */
    public declare isEnabled: boolean;
  2. Build the API docs.
  3. Open the generated API docs page for that member.

A concrete example can be seen in Plugin#isEnabled:

  • source: packages/ckeditor5-core/src/plugin.ts
  • docs page: module_core_plugin-Plugin.html

For comparison, a similar member that includes inline experimental notice text renders the badge correctly, e.g. Plugin#customExperimentalProp.

✔️ Expected result

A member explicitly annotated with @experimental should be rendered as experimental in the generated API docs, even if the JSDoc does not include an additional inline Experimental: notice in the description.

❌ Actual result

The experimental badge is not rendered for members that use only:

@experimental

without extra notice text in the summary.

In practice, this means that two members annotated with @experimental may render differently depending on whether the description also contains an inline Experimental: notice.

❓ Possible solution

The docs pipeline should preserve explicit @experimental annotations on members regardless of whether the summary contains an inline Experimental: sentence.

If there is logic intended to prevent class-level @experimental from cascading to all children, it should distinguish between:

  • truly inherited/cascaded @experimental, and
  • explicitly declared member-level @experimental

This is worth fixing because the current behavior is surprising for contributors, makes @experimental usage inconsistent, and causes downstream API docs tooling to render incorrect badges for valid source annotations.

📃 Other details

  • Browser: N/A – build-time API docs issue
  • OS: macOS
  • First affected CKEditor version: latest
  • Installed CKEditor plugins: N/A

Metadata

Metadata

Assignees

Labels

squad:platformIssue to be handled by the Platform team.status:in-progressSet automatically when an issue lands in the "In progress" column. We are working on it.type:bugThis issue reports a buggy (incorrect) behavior.

Type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions