Add JavaDoc #39
Add JavaDoc #39
Conversation
also refine exception types
| * inside this class can both be retrieved ({@link DefaultServiceBindingAccessor#getInstance()}) <bold>and</bold> | ||
| * manipulated ({@link DefaultServiceBindingAccessor#setInstance(ServiceBindingAccessor)}). Applications might want to | ||
| * overwrite the default instance during startup to tweak the default behavior of libraries that are relying on this | ||
| * fallback. <br> |
There was a problem hiding this comment.
Where is the term "fallback" coming from? I only see that you can change the statically stored instance...
There was a problem hiding this comment.
I tried to improve the wording.
| * fallback. <br> | ||
| * <bold>Please note:</bold> It is considered best practice to offer APIs that accept a dedicated | ||
| * {@link ServiceBindingAccessor} instance instead of using the globally available instance stored inside this class. | ||
| * For example, libraries that are using {@link ServiceBindingAccessor}s should offer APIs such as the following: |
There was a problem hiding this comment.
I think that if you offer to manage the global state there is a good chance people will use that, regardless of what the javadoc states 😉
Anyhow, for that purpose the naming "accessor" sounds somewhat odd..
There was a problem hiding this comment.
Anyhow, for that purpose the naming "accessor" sounds somewhat odd..
I've created an issue to consider renaming the Accessors.
...ess-api/src/main/java/com/sap/cloud/environment/servicebinding/api/ServiceBindingMerger.java
Show resolved
Hide resolved
...ess-api/src/main/java/com/sap/cloud/environment/servicebinding/api/ServiceBindingMerger.java
Show resolved
Hide resolved
...ess-api/src/main/java/com/sap/cloud/environment/servicebinding/api/ServiceBindingMerger.java
Show resolved
Hide resolved
...ain/java/com/sap/cloud/environment/servicebinding/SapVcapServicesServiceBindingAccessor.java
Show resolved
Hide resolved
...ava/com/sap/cloud/environment/servicebinding/SapServiceOperatorServiceBindingIoAccessor.java
Show resolved
Hide resolved
...-operator/src/main/java/com/sap/cloud/environment/servicebinding/LayeredParsingStrategy.java
Outdated
Show resolved
Hide resolved
| import com.sap.cloud.environment.servicebinding.api.ServiceBinding; | ||
|
|
||
| /** | ||
| * A {@link LayeredParsingStrategy} that expects all property files to contain "plain" text (i.e. no JSON structures). |
There was a problem hiding this comment.
Maybe add an @see to the interface. The second sentence doesn't really make sense to me, I mean all properties are recognised by their name. In what format should credentials and metadata be? are they directories instead?
There was a problem hiding this comment.
Maybe add an @see to the interface.
Where would you point to?
I mean all properties are recognised by their name.
Not really. The LayeredSecretKeyParsingStrategy, for example, distinguishes metadata and credentials properties by their structure instead - the one and only JSON file contains the credentials whereas all other (plain text) files contain metadata. The name of the credentials file doesn't matter.
In what format should credentials and metadata be? are they directories instead?
Not sure what you mean here... The doc already says "property files [...] contain "plain" text (i.e. no JSON structures).".
I thought that would be pretty clear?
There was a problem hiding this comment.
yes the contrast to the other strategy is helpful here 👍🏻
...om/sap/cloud/environment/servicebinding/SapServiceOperatorLayeredServiceBindingAccessor.java
Show resolved
Hide resolved
| import com.sap.cloud.environment.servicebinding.api.ServiceBinding; | ||
|
|
||
| /** | ||
| * A {@link LayeredParsingStrategy} that expects all property files to contain "plain" text (i.e. no JSON structures). |
There was a problem hiding this comment.
yes the contrast to the other strategy is helpful here 👍🏻
This PR adds JavaDoc to all public APIs.
Release Notes
Module:
java-access-apicom.sap.cloud.environment.servicebinding.api.exception.ServiceBindingAccessException.Module:
java-consumption-apiTypedMapView#getEntriesnow also returns all entries that are subtypes (Class#isAssignableFrom) of the queried entry type.TypedListView#getItemsnow also returns all items that are subtypes (Class#isAssignableFrom) of the queried item type.com.sap.cloud.environment.servicebinding.api.exception.ValueCastException.com.sap.cloud.environment.servicebinding.api.exception.KeyNotFoundException.Module:
java-sap-service-operatorcom.sap.cloud.environment.servicebinding.metadata.BindingMetadatacom.sap.cloud.environment.servicebinding.metadata.BindingMetadataFactorycom.sap.cloud.environment.servicebinding.metadata.BindingPropertycom.sap.cloud.environment.servicebinding.metadata.PropertyFormat