Bug 530953 - Bad UML usage documentation
Summary: Bad UML usage documentation
Status: NEW
Alias: None
Product: Acceleo
Classification: Modeling
Component: Documentation (show other bugs)
Version: unspecified   Edit
Hardware: PC Windows 10
: P3 normal
Target Milestone: ---   Edit
Assignee: Project Inbox CLA
QA Contact:
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2018-02-09 10:57 EST by Ed Willink CLA
Modified: 2018-06-07 16:04 EDT (History)
1 user (show)

See Also:

Attachments
Add an attachment (proposed patch, testcase, etc.)

Note You need to log in before you can comment on or make changes to this bug.
Description Ed Willink CLA 2018-02-09 10:57:12 EST 
The autogenerated Generate contains the text:

		/*
		 * TODO If you need additional resource factories registrations, you can register them here. the following line
		 * (in comment) is an example of the resource factory registration for UML.
		 *
		 * If you want to use the generator in stand alone, the resource factory registration will be required.
		 *
		 * To learn more about the registration of Resource Factories, have a look at the Acceleo documentation (Help -> Help Contents).
		 */

		// resourceSet.getResourceFactoryRegistry().getExtensionToFactoryMap().put(UMLResource.FILE_EXTENSION, UMLResource.Factory.INSTANCE);

This is VERY wrong.

The golden rule for UML usage is that applications must call some variant of UMLResourcesUtil.init
Comment 1 Laurent Goubet CLA 2018-02-12 04:24:04 EST 
This is wrong now, but was the case when this comment was generated since UML was a nightmare to initialize. You can also find that outdated information on the UML FAQ at https://wiki.eclipse.org/MDT/UML2/FAQ#What.27s_required_to_load_a_UML_.28.uml.29_resource_from_a_standalone_application.3F .

The generated comment needs to be changed for UMLResourceUtils now.
Comment 2 Eclipse Genie CLA 2018-02-12 04:34:48 EST 
New Gerrit change created: https://git.eclipse.org/r/117142
Comment 3 Ed Willink CLA 2018-02-12 05:02:34 EST 
The new comment is just confusing to a non-UML expert; most Acceleo newbies.

It should be possible to search through the generated main template for "UML" and find a positive recommendation for exactly what to uncomment for eaverything necessary for UML.

Instead there is a residual old comment followed by an undermining new comment that says to use call "UMLResourcesUtil.init(resourceSet)".

Suggest a three level option in the comment.

Firstly a generic description that for very simple models without a custom resource:

// resourceSet.getResourceFactoryRegistry().getExtensionToFactoryMap().put("xxx", new XMIResourcefactoryImpl());

Then a generic description that for simple models with a custom resource:

// resourceSet.getResourceFactoryRegistry().getExtensionToFactoryMap().put(XXXResource.FILE_EXTENSION, XXXResource.Factory.INSTANCE);

Finally a description that more sophisticated models such as UML need more comprehensive helper utility functions.

// UMLResourcesUtil.init(resourceSet);
Comment 4 Laurent Goubet CLA 2018-02-12 05:24:24 EST 
The new comment is there for UML users that want to use an Acceleo generator targetting UML in standalone.

The "old" comment is there to explain to users how to "register a resource factory" which targets more than just UML. We could have a standalone comment with UMLResourcesUtil, I'll see to that later.
Comment 5 Laurent Goubet CLA 2018-02-23 05:29:26 EST 
Looks like the connection between bugzilla and gerrit isn't working. new change created to outline UMLResourcesUtil :  https://git.eclipse.org/r/117142
Comment 6 Ed Willink CLA 2018-02-23 05:43:36 EST 
(In reply to Ed Willink from comment #3)
> Finally a description that more sophisticated models such as UML need more
> comprehensive helper utility functions.
> 
> // UMLResourcesUtil.init(resourceSet);

and of course for the many users who need to know to invoke an Xtext generated

MyDSLStandaloneSetup.doSetup()