Community
Participate
Working Groups
Javadoc problems in new E4 APIs: http://download.eclipse.org/eclipse/downloads/drops4/I20130428-2000/compilelogs/platform.doc.isv.javadoc.txt > ../../../eclipse.platform.ui/bundles/org.eclipse.e4.ui.model.workbench/src/org/eclipse/e4/ui/model/application/ui/MElementContainer.java:61: warning - Tag @link: reference not found: T This is a bug, but AFAICS, this Javadoc is generated, so I didn't just go and fix it. The {@link T} is not supported, since "T" is a type parameter. Fix is to use {@code T}. If you really need the proprietary Javadoc tags @generated, @model, and @ordered, then please add a corresponding '-tag ...' line in platformOptions.txt. However, Javadoc tags are deprecated and should really be replaced by @Documented annotations, e.g. javax.annotation.Generated.
On the platform UI call today we decided to ignore the EMF tags, so I will addd the following tag options to platformOptions.txt: -tag 'model:x:EMF generated tag' -tag 'generated:x:EMF generated tag' -tag 'ordered:x:EMF generated tag' As for the bad @link, I will update the generator and the code to use @code
(In reply to comment #1) Sounds good, but according to [1], the :X: must be uppercase and the title should be enclosed in "", i.e.: -tag 'model:X:"EMF generated tag"' [1] http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#tag
Pushed doc fix (tags + missing package) to: http://git.eclipse.org/c/platform/eclipse.platform.common.git/commit/?id=a80d7bb67aefecaf4a5d6c9cf607cd8cb2d192b5 Changing the {@link T} to {@code T} will be a bit more problematic, since the doc generator has some code in it to simply get the qualified name of whatever appears in the list. I'm not sure if the generator even has a way to know the difference between a type and a type parameter.
> Changing the {@link T} to {@code T} will be a bit more problematic, since > the doc generator has some code in it to simply get the qualified name of > whatever appears in the list. I'm not sure if the generator even has a way > to know the difference between a type and a type parameter. Formally, Javadoc links always use the erasure of types. In this case, that's the leftmost bound of the type parameter, so the correct @link target would be: * The list contents are of type {@link MUIElement}. This would pin down the type and hence lose stricter bounds in subtypes. The Javadoc in subtypes is broken anyway, see e.g. MenuImpl: /** * <!-- begin-user-doc --> * <!-- end-user-doc --> * @generated */ public List<MMenuElement> getChildren() { This misses an {@inheritDoc} in the main description and therefore leaves the Javadoc empty.
The @link warning is a problem with the EMF code generator. I have submitted bug 408617 to track it.
Sounds like this bug should be deferred then. The releng tests that would catch this don't run anyway [1], so the only real effect is a short message in compilelogs/platform.doc.isv.javadoc.txt [1] /eclipse.platform.releng.aggregator/eclipse.platform.releng.tychoeclipsebuilder/eclipse-junit-tests/src/main/scripts/test.xml says: <!-- remove for now, bug 400385 <antcall target="relEng" /> -->
Moving to 4.3.1 as we are still waiting for bug 402402 to address the generated doc issues.
Bug 402402 was resolved in EMF's 2.10 (Luna) stream. We may need to retarget this for 4.4.
...and on to M3 since Paul Elder is away...
Fixed indirectly by the model regeneration for bug 421462.
Verified in http://download.eclipse.org/eclipse/downloads/drops4/I20131210-2000/compilelogs/platform.doc.isv.javadoc.txt
