Transfer UML attribute or class comments to source code of generated entities #46

mkresse · 2015-08-26T15:19:55Z

Hi there,

the XMI format allows the definition of comments for classes or attributes (via the <ownedComment> element). When using the jhipster-uml generator, it would be great if the generator would recognize such comments and include them as javadoc comment in the generated entity class.
This way, the UML model could be used not only as model for the generator, but also as documentation of the entity model.

MathieuAA · 2015-08-26T16:47:31Z

Hi!

That's a pretty good idea! But that's the good part =).
Here comes the bad one: my main concern is that the JSON format can't have any comment, and we'd have to add yet another field in the JSON, and this field may (or may not) have a pretty big (in term of string length) value.
But then, the comments could be added directly to the templates, which is nice.

Let's have the input of the JHipster 6 @jdubois, @andidev, @deepu105, @gmarziou, @atomfrede, @gzsombor on this, but you have my "+1".

deepu105 · 2015-08-27T01:35:52Z

We can have the comment text as an optional parameter for the json and that
will be easier to handle so that in Jhipster templates you just need to
print it in a comment block
On 27 Aug 2015 00:47, "Mathieu ABOU-AICHI" notifications@github.com wrote:

Hi!

That's a pretty good idea! But that's the good part =).
Here comes the bad one: my main concern is that JSON can't have any
comment.

We rely too much on the JSON dumped (and consumed) by JHipster that it
would be pretty hard, if not impossible, to achieve this.
That being said, if JHipster could take another format as input, or
another form of input...
The comments could be added directly to the templates.

Let's have the input of the JHipster 6 @jdubois
https://github.com/jdubois, @andidev https://github.com/andidev,
@deepu105 https://github.com/deepu105, @gmarziou
https://github.com/gmarziou, @atomfrede https://github.com/atomfrede,
@gzsombor https://github.com/gzsombor on this.

—
Reply to this email directly or view it on GitHub
#46 (comment)
.

andidev · 2015-08-27T06:25:39Z

@deepu105 suggestion gives a minimal impact on the generator so I say this is doable if wanted.
I could implement this in jhipster if wanted though I would like to have an example of where the comments should be placed and how they should look. I guess as javadoc comments for class and field? Not sure how to handle linebreaks though. Any suggestions on that?

mkresse · 2015-08-27T09:30:03Z

@andidev Regarding the question if this feature is wanted enough: I think it would be a very useful feature and I would definitely use it. However I have no idea, how the majority of the jhipster-uml users utilize the software and whether it would support their workflow.

Regarding the implementation: class comments appear directly within the packagedElement class, an example produced by Modelio 3.3 looks like:

    <packagedElement xmi:type="uml:Class" xmi:id="_lZ6hZkyUEeWd98JY82OrEw" name="MyCoolClass">
        <ownedComment xmi:type="uml:Comment" xmi:id="_lZ6hZ0yUEeWd98JY82OrEw">
            <body>&lt;p&gt;This class represents the Magna ligula pellentesque. Lacus ut sed. Himenaeos litora et posuere. Accumsan purus inceptos. Ultricies praesent metus. /* Fames odio quam. */&lt;/p&gt;&lt;p&gt;TODO:&lt;/p&gt;

                &lt;ul&gt;
                &lt;li&gt;first &amp;uuml;ber&lt;/li&gt;
                &lt;li&gt;second&lt;/li&gt;
                &lt;/ul&gt;
            </body>
        </ownedComment>
    </packagedElement>

The body element contains plain html, which could be used as class comment without much modification (xml entity decoding assumed):

/**
 * <p>This class represents the Magna ligula pellentesque. Lacus ut sed. Himenaeos litora et posuere. Accumsan purus inceptos. Ultricies praesent metus. &#47;* Fames odio quam. *&#47;</p><p>TODO:</p>
 *
 * <ul>
 * <li>first &uuml;ber</li>
 * <li>second</li>
 * </ul>
 */
@Entity
@Table(name = "MYCOOLCLASS")
public class MyCoolClass {

New lines should be prefixed with " * " for nicer code layout and "*/" or in general slashes should be escaped using corresponding entity (/). Since line breaking is recommended (http://www.oracle.com/technetwork/articles/java/index-137868.html), due to html being insensitive to line feeds, a simple word wrap algorithm could be used:

/**
 * <p>This class represents the Magna ligula pellentesque. Lacus ut sed. Himenaeos
 * litora et posuere. Accumsan purus inceptos. Ultricies praesent metus. &#47;*
 * Fames odio quam. *&#47;</p><p>TODO:</p>
 *
 * <ul>
 * <li>first &uuml;ber</li>
 * <li>second</li>
 * </ul>
 */

Attribute comments appear within <ownedAttribute> elements and should probably be transferred as a comment of the field declaration. Generally I suppose the same rules would apply. Maybe, since Modelio puts even on liners within <p> elements, stripping of enclosing paragraph elements might be a good idea?

MathieuAA · 2015-08-27T10:18:56Z

@mkresse yes, parsing the comments from modelio XMI files seems easy, but don't forget the others!
If JHipster adds the support for comments, then JHipster-UML will too. It's an option worth the work.

andidev · 2015-08-29T20:12:36Z

So jhipster support for javadoc comments is ready to be merged! see PR jhipster/generator-jhipster#1952 for an example of how the json should look like and what will be generated.

MathieuAA · 2015-08-29T21:36:12Z

Ok! It should be ready next week in JHipster-UML (I hope so anyway, if we have time).
Great work by the way!

mkresse · 2015-08-31T09:55:44Z

Wow, this looks really great - can't wait to try it out. Thanks a lot for your work.

MathieuAA · 2015-09-27T10:07:10Z

Closing this thread as the comment support has been added to JHipster-UML, the documentation will soon be updated too.

MathieuAA added the enhancement label Aug 26, 2015

This was referenced Aug 29, 2015

Add support for Class and Field javadoc comments to entity generator jhipster/generator-jhipster#1949

Closed

add class and field comments to entity generator jhipster/generator-jhipster#1952

Merged

MathieuAA assigned CarlKlagba Sep 4, 2015

MathieuAA unassigned CarlKlagba Sep 26, 2015

MathieuAA closed this as completed Sep 27, 2015

MathieuAA added the commenting label Oct 31, 2015

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Transfer UML attribute or class comments to source code of generated entities #46

Transfer UML attribute or class comments to source code of generated entities #46

mkresse commented Aug 26, 2015

MathieuAA commented Aug 26, 2015

deepu105 commented Aug 27, 2015

andidev commented Aug 27, 2015

mkresse commented Aug 27, 2015

MathieuAA commented Aug 27, 2015

andidev commented Aug 29, 2015

MathieuAA commented Aug 29, 2015

mkresse commented Aug 31, 2015

MathieuAA commented Sep 27, 2015

Transfer UML attribute or class comments to source code of generated entities #46

Transfer UML attribute or class comments to source code of generated entities #46

Comments

mkresse commented Aug 26, 2015

MathieuAA commented Aug 26, 2015

deepu105 commented Aug 27, 2015

andidev commented Aug 27, 2015

mkresse commented Aug 27, 2015

MathieuAA commented Aug 27, 2015

andidev commented Aug 29, 2015

MathieuAA commented Aug 29, 2015

mkresse commented Aug 31, 2015

MathieuAA commented Sep 27, 2015