Bugzilla – Full Text Bug Listing
| Summary: | Provide a way to suppress generated Java docs. | ||||||
|---|---|---|---|---|---|---|---|
| Product: | [Modeling] EMF | Reporter: | Thomas Hallgren <thomas> | ||||
| Component: | Tools | Assignee: | Kenn Hussey <Kenn.Hussey> | ||||
| Status: | VERIFIED FIXED | QA Contact: | |||||
| Severity: | enhancement | ||||||
| Priority: | P3 | CC: | Ed.Merks, Kenn.Hussey | ||||
| Version: | unspecified | ||||||
| Target Milestone: | M1 | ||||||
| Hardware: | All | ||||||
| OS: | All | ||||||
| Whiteboard: | |||||||
| Attachments: |
|
||||||
This could be achieved by introducing an override point for the Javadoc in the Class.javajet template. A third flag is also needed to suppress generated documentation on getters and setters. Consider the following: /** * Returns the value of the '<em><b>Email</b></em>' attribute. * <!-- begin-user-doc --> * <p> * If the meaning of the '<em>Email</em>' attribute isn't clear, there really should be more of a description here... * </p> * <!-- end-user-doc --> * <!-- begin-model-doc --> * The users email * <!-- end-model-doc --> * * @return the value of the '<em>Email</em>' attribute. * @see com.cloudsmith.hammer.auth.AuthPackage#getUser_Email() * @model transient="true" changeable="false" volatile="true" * @generated */ String getEmail(); What I would like is: /** * <!-- begin-model-doc --> * The users email * <!-- end-model-doc --> * * @return the value of the '<em>Email</em>' attribute. * @model transient="true" changeable="false" volatile="true" * @generated */ String getEmail(); Suppressing "user-doc" would remove some of it but not all. I would also like to suppress: 1. The first sentence before the <!--begin-user-doc--> 2. The @see clause referencing the package Ideally, I'd also like a way to customize the text for the @return tag. (In reply to comment #2) We can provide override points for each of the javadoc sections that appear in the interfaces... Given you can already remove the user-doc section and then edit to your heart's content, I'm not sure what you'd do with all the template overrides. I suppose you'd generate an empty user-doc section, still include the model doc (which otherwise wouldn't merge to pick up changes, but nothing else? (In reply to comment #4) > Given you can already remove the user-doc section and then edit to your heart's > content, I'm not sure what you'd do with all the template overrides. See bug 354525 comment 2. The model is the primary source. The Java code is just one possible generation that stems from that model. (In reply to comment #4) > Given you can already remove the user-doc section and then edit to your heart's > content, I'm not sure what you'd do with all the template overrides. I suppose > you'd generate an empty user-doc section, still include the model doc (which > otherwise wouldn't merge to pick up changes, but nothing else? Yes, it would include the user section for hand-customization but the format/content of everything else could be changed. In this case, Thomas would probably just leaving out everything exception the model documentation and the @generated annotation... Created attachment 201349 [details]
proposed changes
Here's a patch that adds an override point for the interface Javadoc. The following Javadoc override points already existed:
Class/getGenFeature.javadoc.override.javajetinc
Class/setGenFeature.javadoc.override.javajetinc
Class/unsetGenFeature.javadoc.override.javajetinc
Class/isSetGenFeature.javadoc.override.javajetinc
Class/genOperation.javadoc.override.javajetinc
The changes have been committed to CVS. The changes are available in integration build I201108291838. |
EMF emits a Javadoc clause for classes and interfaces where, in many cases, some sections are irrelevant and even confusing to the intended user. It would be great if there was a way to suppress it. Ideally, I would like the documentation to look like this: /** * <!-- begin-model-doc --> * An abstract representation of the Cloudsmith user. * * @see UserProvider * <!-- end-model-doc --> * @model interface="true" abstract="true" * @generated */ instead of as today: /** * <!-- begin-user-doc --> * A representation of the model object '<em><b>User</b></em>'. * <!-- end-user-doc --> * * <!-- begin-model-doc --> * An abstract representation of the Cloudsmith user. * * @see UserProvider * <!-- end-model-doc --> * * <p> * The following features are supported: * <ul> * <li>{@link com.cloudsmith.hammer.auth.User#getLogin <em>Login</em>}</li> * <li>{@link com.cloudsmith.hammer.auth.User#getEmail <em>Email</em>}</li> * <li>{@link com.cloudsmith.hammer.auth.User#getName <em>Name</em>}</li> * <li>{@link com.cloudsmith.hammer.auth.User#getGravatarId <em>Gravatar Id</em>}</li> * </ul> * </p> * * @see com.cloudsmith.hammer.auth.AuthPackage#getUser() * @model interface="true" abstract="true" * @generated */ Perhaps two new "Suppress" flags could be added to the genmodel? Suppress "user-doc" true/[false] This flag would affect all places where the <!-- begin-user-doc --><!--end-user-doc --> tags are found and simply suppress the whole thing, tags and all. Suppress class/interface javadoc true/[false] Would suppress everything generated in the class/interface header between the <!--end-model-doc> and the @model tag (non inclusive of course since @model is controlled by another flag).