Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

Bug 406780

Summary: [Model] Javadoc problems in new E4 APIs
Product: [Eclipse Project] Platform Reporter: Markus Keller <markus.kell.r>
Component: UIAssignee: Paul Elder <pelder.eclipse>
Status: VERIFIED FIXED QA Contact: Paul Elder <pelder.eclipse>
Severity: normal    
Priority: P3 CC: daniel_megert, emoffatt, john.arthorne, Michael_Rennie, pelder.eclipse
Version: 4.3   
Target Milestone: 4.4 M4   
Hardware: All   
OS: All   
Whiteboard:
Bug Depends on: 402402    
Bug Blocks: 403190    

Description Markus Keller CLA 2013-04-29 06:08:01 EDT 
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.
Comment 1 Michael Rennie CLA 2013-05-02 11:06:40 EDT 
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
Comment 2 Markus Keller CLA 2013-05-02 12:10:12 EDT 
(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
Comment 3 Michael Rennie CLA 2013-05-07 11:14:20 EDT 
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.
Comment 4 Markus Keller CLA 2013-05-07 11:42:15 EDT 
> 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.
Comment 5 Paul Elder CLA 2013-05-21 13:55:19 EDT 
The @link warning is a problem with the EMF code generator. I have submitted bug 408617 to track it.
Comment 6 Markus Keller CLA 2013-05-21 14:30:01 EDT 
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" /> -->
Comment 7 Michael Rennie CLA 2013-05-22 10:46:43 EDT 
Moving to 4.3.1 as we are still waiting for bug 402402 to address the generated doc issues.
Comment 8 Paul Elder CLA 2013-07-17 09:58:02 EDT 
Bug 402402 was resolved in EMF's 2.10 (Luna) stream. We may need to retarget this for 4.4.
Comment 9 Eric Moffatt CLA 2013-09-13 14:06:02 EDT 
...and on to M3 since Paul Elder is away...
Comment 10 Paul Elder CLA 2013-12-11 12:58:27 EST 
Fixed indirectly by the model regeneration for bug 421462.