Community
Participate
Working Groups
I added model documentation to my enum literals using the "Sample Ecore Model Editor". The XML for an enum literal looks like this: <eLiterals name="PERFECT" value="1"> <eAnnotations source="http://www.eclipse.org/emf/2002/GenModel"> <details key="documentation" value="Version must match exactly the specified version."/> </eAnnotations> </eLiterals> After successful Java code generation I don' t find any documentation in the generated literals. Instead, the generated integer constant receives the documentation. This must be wrong. The integer constant is less significant and the documentation should be attached to the enum literal. Sample generated code: /** * The '<em><b>PERFECT</b></em>' literal object. * <!-- begin-user-doc --> * <!-- end-user-doc --> * * @see #PERFECT_VALUE * @generated * @ordered */ PERFECT(1, "PERFECT", "PERFECT"), /** * The '<em><b>PERFECT</b></em>' literal value. * <!-- begin-user-doc --> * <!-- end-user-doc --> * <!-- begin-model-doc --> * Version must match exactly the specified version. * <!-- end-model-doc --> * * @see #PERFECT * @model * @generated * @ordered */ public static final int PERFECT_VALUE = 1;
The fact it's coming out in the same place as where the @model appears isn't an accident. With Java 1.4 the integer constants were heavily used in switches. Also, when defining a model from annotated Java, a class with a few integer constants was easy to write. Whether the current approach is ideal for Java 5.0 is definitely more debatable, so I'll mark it as an enhancement, though one we're unlikely to find time to implement.
I can see that historically, before enums were supported in Java, other solutions was necessary, but I don't think this bug can be thought of as an "enhancement" unless you say that EMF isn't really intended to support for Java 5. Enums get their documentation in the wrong place. That's a bug. Fixing it, like fixing all bugs, will of course enhance the usage of the generator, but in this context, it's definitely a bug IMHO.
I've changed it to generate the model doc in both places. http://git.eclipse.org/c/emf/org.eclipse.emf.git/commit/?id=95c28e355e733e481570d6e46429ca9b71dec075
The changes are available in the Photon release later today and in http://download.eclipse.org/modeling/emf/emf/builds/release/2.14