[abrahamwolk]

This pull request implements the proposal described in #140 (comment).

This pull request is part of work on adding the functionality to represent a description in more types of the library in order to support display descriptions for these types in the PV Table application in Phoebus. I will create a separate pull request to Phoebus with the added functionality to the PV Table application. Update 2026-10-19: the following is the accompanying pull request to Phoebus with the added functionality to the PV Table application: ControlSystemStudio/phoebus#3967

Changes. The following changes are implemented in this pull request:

1. The following interface DescriptionProvider is added:

public interface DescriptionProvider {
    public Optional<String> getDescription();
}

2. The interface DisplayProvider is changed so that it (1) extends DescriptionProvider and (2) provides a default implementation of getDescription(): 6d27ff8
3. The abstract classes VString, VEnum, and VBoolean are declared to implement the new interface DescriptionProvider, and implementations of getDescription() are added to their implementations IVString, IVEnum, and IVBoolean. The implementation is backwards compatible in the following way: new methods .of() are implemented for VString, VEnum, and VBoolean that also (in addition to the arguments of the existing .of()-methods) take a description as an argument (or Optional.empty(), if no description exists). For backwards compatibility, the old .of()-methods are left in place, calling the new .of()-methods with Optional.empty() for the description. The old .of()-methods have been marked @Deprecated.

Deprecation of previous functionality. The intention is to add the new functionality in a backwards compatible way, deprecating the old functionality. The idea is that after some time (perhaps years), when projects dependent on the epics-vtypes have been updated to use the new .of()-methods, the deprecated .of()-methods can be removed.

One design decision to be aware of. The field description has not been added to the implementations of equals() and hashCode() of VString, VEnum, and Vboolean, in order to maximize backwards compatibility. I believe that the "correct" point in time to add the description field to the logic of these functions is when the deprecated .of()-methods are removed.

Versioning. One final point is the versioning of the epics-vtype library. At the moment, the pull request forsees merging these changes into 1.0.9-SNAPSHOT. Does epics-vtype use semantic versioning? If so, should the version be increased to 1.1.0-SNAPSHOT in order to reflect the (backwards compatible) API change?

[abrahamwolk]

I now see that there is one unresolved question in this implementation: VEnum has a method EnumDisplay getDisplay(), which, in turn, may return an AdvancedEnumDisplay, which may contain a Display, which may contain a description. What does AdvancedEnumDisplay represent, and how should the possible presence of AdvancedEnumDisplay be handled?

[abrahamwolk]

I now see that there is one unresolved question in this implementation: VEnum has a method EnumDisplay getDisplay(), which, in turn, may return an AdvancedEnumDisplay, which may contain a Display, which may contain a description. What does AdvancedEnumDisplay represent, and how should the possible presence of AdvancedEnumDisplay be handled?

The possibility of an AdvancedEnumDisplay being present in the case of values of type VEnum is handled as a special case in the accompanying pull request (ControlSystemStudio/phoebus#3967) that implements the accompanying changes in the PV Table application in Phoebus (this mirrors the structure of the existing implementation), by the following line: https://github.com/ControlSystemStudio/phoebus/blob/8d869c7b506d5243d87c4b2c5a4e799b7ade5514/app/pvtable/src/main/java/org/phoebus/applications/pvtable/model/PVTableItem.java#L207

[jacomago]

Maybe add an overload so the api is backwards compatible.

[abrahamwolk]

IVBoolean is not part of the API: neither the constructor nor the class IVBoolean are visible outside of the package (they are not declared public).

[jacomago]

I think maybe there is a sonarlint against having Optionals for input params, but not sure...

[abrahamwolk]

I think it's better to encode the intent in the type, and representing the absence of a description by Optional.empty().