Date & Time controls: Overview cut off along with broken format in API Reference

[boghyon]

OpenUI5 version

Since https://github.com/SAP/openui5/commit/49782b00fbec7394deb32254681e708d129589ff

URL (minimal example if possible)

• https://sdk.openui5.org/nightly/#/api/sap.m.DatePicker
• https://sdk.openui5.org/nightly/#/api/sap.m.DateRangeSelection
• https://sdk.openui5.org/nightly/#/api/sap.m.DateTimePicker
• https://sdk.openui5.org/nightly/#/api/sap.m.TimePicker

Steps to reproduce the problem

1. Open above API Reference pages.
2. Compare each page with the actual JSDoc comments of the respective control in the source code.
3. Notice how the Overview section in the control's API Reference page is incomplete.

The rest of the description with examples is mentioned in the Constructor section with broken format.

Analysis

It looks like the JSDoc tag @example is not compatible within <ul><li> tags even with <pre>.

For example:

1. Given the following <ul>...</ul> that contains @example: https://github.com/SAP/openui5/blob/7660bd4b7220dcc34aa44248c8a3ff2dd1232df9/src/sap.m/src/sap/m/DatePicker.js#L112-L151
2. The generated https://sdk.openui5.org/nightly/test-resources/sap/m/designtime/apiref/api.json contains the following invalid "description" HTML node which ends with </p> despite the open <ul>:

   <!-- ... --><p><ul><li>Use the <code>value</code> property if you want to bind the <code>DatePicker</code> to a model using the <code>sap.ui.model.type.Date</code></li></p>
   

Any other information? (attach screenshot if possible)

Rather than having specific code snippets with @example, it would be better if the documentation topic "Dates, Times, Timestamps, and Time Zones" could be promoted and highlighted in the API reference, which I personally consider crucial information for every UI5 dev dealing with date & time related controls.

[codeworrior]

These are wrong usages of the @example tag. @example in JSDoc is a so called block tag which means, when it appears, it automatically ends the previous block tag (here: the implicit @description tag).

In other words: @example tags cannot be nested into the description of an API.

The remainder of the description therefore becomes part of the content of the last @example tag. The SDK then shows all examples as part of the constructor.

[s-todorova]

Hello @boghyon, Thank you for sharing this finding. I've created an internal incident 2380097696. The status of the issue will be updated here in GitHub. Regards, Siyana

[niyap]

Hello @boghyon

The documentation was adjusted with the following commit 158095e

Kind Regards, Niya