DataSourceDefinition docs are confusing

[nlisker]

https://jakarta.ee/specifications/platform/11/apidocs/jakarta/annotation/sql/datasourcedefinition:

In the above example, the databaseName, user and serverName properties were specified as part of the url property and using the corresponding annotation elements. This should be avoided.

There is no example above it.

Also, the correct way to configure a data source in production, e.g., without specifying credentials, should be discussed. Saying "here is how the annotation can be used, don't use it like that" doesn't help much. Tell the user how it should be used.

If the properties annotation element is used and contains a DataSource property that was also specified using the corresponding annotation element, the annotation element value takes precedence. For example:

This would result in the following values being used when configuring the DataSource:

There is no example here either.

Examples:

Using a URL:

An example lookup of the DataSource from an Jakarta Enterprise Beans:

There's nothing here either.

Looks like your @snippet tags aren't being rendered.