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

Bug 354525

Summary:	No model-doc is generated or updated if user-doc is removed.
Product:	[Modeling] EMF	Reporter:	Thomas Hallgren <thomas>
Component:	Core	Assignee:	Ed Merks <Ed.Merks>
Status:	RESOLVED WONTFIX	QA Contact:
Severity:	normal
Priority:	P3	CC:	Kenn.Hussey
Version:	unspecified
Target Milestone:	---
Hardware:	All
OS:	All
Whiteboard:

Description Thomas Hallgren

2011-08-11 12:35:06 EDT

If I remove the generated <!-- begin-user-doc --><!-- end-user-doc --> completely, tags and all, then <!-- begin-model-doc --><!-- end-model-doc --> is no longer generated. If I generate the model-doc before I remove the user-doc, then the generator stops applying updates to the model-doc.

In short, in order for the model-doc to function, the user-doc tags must be present.

Comment 1 Ed Merks

2011-08-11 12:43:42 EDT

Yes, that's how it works.  Everything outside of the user-doc section can be replaced during merging.  If you remove the user-doc section, merging isn't supported and you have complete control.  This would solve your other problem too; just write the documentation you want and turn off merging.  Be sure to include @generated or merging for the Java content will be disabled too.

Comment 2 Thomas Hallgren

2011-08-11 14:06:41 EDT

I want to maintain my documentation in the model, not in the generated java classes. A major reason for using a model is that I can generate interfaces for other languages should a need for that arise.

The user-doc is Java only. It's never in my model. Yet, it affects how the documentation that I have in my model is represented and updated. To me, the model-doc is primary and the user-doc is redundant. So, no, removing the user-doc from the java code doesn't come close to solve my problem. I'm reopening this bug.

Comment 3 Ed Merks

2011-08-11 14:12:19 EDT

As I said, this is working as designed and intended.  I.e., it's not a bug and it won't be fixed because it's not broken. You already have another bugzilla requesting all the your Javadoc flexibilities you desire, so best you focus on that rather than on insisting that feature being a bug.

Comment 4 Thomas Hallgren

2011-08-11 14:15:21 EDT

Fair enough, but if this bug isn't fixed, then suppressing the user-doc won't work as expected. It would be very bad if suppressing generation of user-doc meant that all future updates of model-doc is disabled.

Comment 5 Ed Merks

2011-08-11 14:19:25 EDT

You have control over the merge rules as well as the templates.  

Keep in mind too that the user-doc section need not contain any content and when it doesn't nothing shows up in the generated Javadoc so you have complete control over the visible content.