Improve JSDoc Documentation for sap.ui.model.json.JSONModel #4346
Description
What is the issue and how can we reproduce it?
The JSDoc documentation for sap.ui.model.json.JSONModel is insufficient for such a critical component of the framework. The JSONModel is the primary way for application developers to store and manage data outside of OData-Models in UI5 applications, yet the current API documentation lacks essential information about behavior, best practices, and limitations. As we stopped using OData in newly made apps due to absurd levels of complexity on both frontend and backend (CAP node) side this is the only model which can be used without heavily investing into writing an own one. (This also would made upgrading more dangerous).
The setData() method only mentions that it "sets the data, passed as a JS object tree, to the model" but doesn't explain what types of data are supported, what happens to existing bindings when data is replaced versus merged, or any performance implications. There are no examples showing proper usage patterns. The method signature mentions it throws an error for cycles with merge, but doesn't explain the general behavior with circular references.
The getProperty() method states it returns "null or undefined" when a property is not found, but doesn't clarify when each case applies. The documentation doesn't explain the path syntax or provide examples of how the context parameter works in practice.
The constructor mentions observation mode but doesn't explain when it should be used, what the performance implications are, or provide concrete examples of the limitations. The note that "newly added or removed properties are not detected" is mentioned but not explained in detail.
Throughout the entire class, there are no @example tags showing real-world usage, no @see links to related documentation topics like Data Binding or Model concepts, and no cross-references to related classes like JSONListBinding or JSONTreeBinding. For a class that's often the first point of contact for developers free style open-UI5 apps, this makes it unnecessarily difficult to understand how to use it correctly.
The JSDoc Guidelines in docs/guidelines/jsdoc.md clearly state that documentation should provide background information required to understand the object, special considerations that apply, and detailed descriptions with additional information. The current JSONModel documentation often only provides a single summary sentence. Improving this documentation would reduce developer confusion, lower the number of support questions, and improve code quality in UI5 applications.
Above was formatted and checked with AI but the message and meaning is formulated by me.
--
Maybe as a side note. In the company where I work our team was merged together will all frontend and fullstack-devs. We have extremely experienced vue and svelte (senior) devs. They are struggling hard to learn openui5. I dont want to discredit any one out of you, but yeah.. I hope you as in UI5 can get some investment in the docs. Not only tutorials which cover only the bascis, but clear API docs how parts should play together. Like models and tables are so heavily interwined. Yet the docs of the table almost do not mention the model at all and vice versa. But as a dev, a full understanding of both parts is required to use the correct APIs. I was told to ping @petermuessig . Sorry. I understand ui5 was mainly written for internal usage and open sourcing it was just like a benefit.
Which OpenUI5 version is your project targeting?
Is the issue device- or browser-specific?
No response
Confirmation
- I have searched the existing issues and reviewed the relevant documentation as well as the API reference.
- I am not disclosing any internal or sensitive information.