Bugzilla – Full Text Bug Listing
| Summary: | User-doc comment on public int fields in PackageClass.javajet | ||
|---|---|---|---|
| Product: | [Modeling] EMF | Reporter: | Alexander Igdalov <alexander.igdalov> |
| Component: | Core | Assignee: | Ed Merks <Ed.Merks> |
| Status: | RESOLVED WONTFIX | QA Contact: | |
| Severity: | enhancement | ||
| Priority: | P3 | CC: | ed |
| Version: | 2.6.0 | ||
| Target Milestone: | --- | ||
| Hardware: | All | ||
| OS: | All | ||
| Whiteboard: | |||
In Bug 298201 MDT/OCL has agreed to relax the current (pre Helios M4) * @noreference This field is not intended to be referenced by clients. inserted by custom templates following the user doc on int fields to /** ... * <!-- begin-user-doc --> * This value may change when the model code is regenerated. * It is subject to change without notice. * <!-- end-user-doc --> ... */ more accurately reflecting the API and avoiding the need for custom templates. The suggestion that the above be auto-generated by an enhanced template capability doesn't quite work. As part of the user-doc, the warning will be re-added on each re-generation. A mechanism to support autogeneration of: /** ... * <!-- begin-user-doc --> * <!-- end-user-doc --> * This value may change when the model code is regenerated. * It is subject to change without notice. ... */ would be useful to MDT/OCL and perhaps all projects that expose models in their APIs. The @maychange suggestion in Bug 298377 may solve the API limuitation. Clients are getting by without this. |
MDT OCL models are sometimes updated and regenerated. As a consequence, the values of constants in generated Package interfaces can change. For example: public interface ExpressionsPackage extends EPackage { ... /** * The feature id for the '<em><b>Start Position</b></em>' attribute. * <!-- begin-user-doc --> * <!-- end-user-doc --> * @generated * @ordered */ int OCL_EXPRESSION__START_POSITION = UtilitiesPackage.TYPED_ELEMENT_FEATURE_COUNT + 0; ... The value assigned to OCL_EXPRESSION__START_POSITION can vary. EMF makes this constant a part of the model code API which is what OCL would like to preserve. But with regard to API tooling, we wouldn't like to declare a breaking change each time such a constant is changed. Thus, we are inclined to use API filters. This would ensure that model updates such as adding a feature or a classifier will not cause API tooling errors. However, we would like to give our clients a hint that they should be careful at using these constants since they can change so that the client code will still be binary compatible with MDT OCL but will not work properly. To do so we would like to include a user-doc comment like /** ... * <!-- begin-user-doc --> * This value may change when the model code is regenerated. * It is subject to change without notice. * <!-- end-user-doc --> ... */ This could be achieved by allowing an optional .javajetinc to be included into the corresponding template code. OCL could provide this custom file to include the desired comment. However, I think this can be considered a more generic task which other clients may want too. Could this user-doc comment be a .genmodel option or even be generated by default? Does it make sense to you? Regards, - Alex.