-
-
Notifications
You must be signed in to change notification settings - Fork 3.7k
@experimental without inline notice is stripped from API docs members #20039
Description
📝 Provide detailed reproduction steps (if any)
- Add a class member with a plain
@experimentalannotation but without an inlineExperimental:notice, for example:/** * Flag indicating whether a plugin is enabled or disabled. * * @experimental * @observable * @readonly */ public declare isEnabled: boolean;
- Build the API docs.
- 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:
@experimentalwithout 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