Documentation consistency: `sap/ui/VersionInfo` vs. `sap.ui.Device`

[pubmikeb]

A consistency issue: for the namespace sap/ui/VersionInfo slashes are used to separate the packages, while for other components dots are used instead, e.g.: sap/ui/VersionInfo vs. sap.ui.Device.

BTW, what's the difference between slashes and dots in the components' name?

P.S. It's a cross-posting of SAP/openui5-docs#63.
Where should I open an API reference/documentation related tickets: https://github.com/SAP/openui5 or https://github.com/SAP/openui5-docs?

[IlianaB]

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

Regards,
Iliana

[codeworrior]

This is not an inconsistency, but needs an explanation. As you might know, UI5 started with global names for its APIs. Creating a button control initially was always done like this

   new sap.m.Button(...}

This still works today, but with the move to AMD (or TS imports when using UI5's TypeScript support), global names for APIs are no longer recommended. Consumers should rather create an AMD dependency (or TS import) and use the local name to access the API:

   sap.ui.define(["sap/m/Button"], function(Button) {
      new Button(...)
   });

   import Button from "sap/m/Button";
   new Button(...)

As UI5 is doomed to compatibility, most APIs are still documented with global names (dot notation). They're however also usable via their module name, like in the above example. The module name is mentioned in the header of the API reference:

Newer APIs that have no more global name are documented with JSDocs module:some/name syntax. It would indeed be more consistent if we would convert all global names in the JSDoc documentation to the module:...syntax. But first, this would be a huge effort without a real improvement of the APIs and second is the new syntax more distracting for the source code reader due to its mandatory prefix and combination of special chars. We therefore rather decided for the above mixture, documenting module-only code with the module:...syntax and everything else with global names.

Back to your question, this means that there's no sap.ui.VersionInfo.load, only import VersionInfo from "sap/ui/VersionInfo"; VersionInfo.load(), but there's indeed sap.ui.Device.browser.chrome as well as import Device from "sap/ui/Device"; Device.browser.chome.

The SDK application decided to unify both syntax forms in one UI. This might create the impression of an inconsistency. But if you think about it, having two separate hierarchies for globals and modules would be harder to grasp.

[pubmikeb]

Thanks a lot for the explanation!
It would great if the documentation would address to this subject.

[pubmikeb]

@codeworrior , should I close this ticket or do you want keep it open?

[codeworrior]

I think we can close this ticket as the inconsistency as such does not exist. The team responsible for the SDK has already several backlog items for improvements of the API reference (often based on input from the SDK's feedback channel). One of the topics is a kind of "legend" for the API reference.