Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.
Bug 354525 - No model-doc is generated or updated if user-doc is removed.
Summary: No model-doc is generated or updated if user-doc is removed.
Status: RESOLVED WONTFIX
Alias: None
Product: EMF
Classification: Modeling
Component: Core (show other bugs)
Version: unspecified   Edit
Hardware: All All
: P3 normal (vote)
Target Milestone: ---   Edit
Assignee: Ed Merks CLA
QA Contact:
URL:
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2011-08-11 12:35 EDT by Thomas Hallgren CLA
Modified: 2011-08-11 14:19 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 Thomas Hallgren CLA 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 CLA 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 CLA 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 CLA 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 CLA 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 CLA 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.