UML syntax: comments

[ronaldtse]

Proposal:

class Class {
  comment "Comment text"
}

Alternative:

class Class {}
comment class Class "Comment text"

[ronaldtse]

We also need to think about:

• multiline comments
• comments on attributes, relationships, etc.

[w00lf]

@ronaldtse i think its better to use the second notation but with slight differences:

class Class {}
comment MyComment {
    text 'My text'
}
MyComment --> Class

Or for attribute:

class Class { 
   attribute my_attribute
}
comment MyComment {
    text 'My text
            multiply lines
            long comment'
}
MyComment --> Class#my_attribute

That way we will keep object notations, like plantuml or dot has and it will be easier to implement. What do you think?

[ronaldtse]

Note that we can have enum Foo and also class Foo so we need to distinguish them in relations.

In the description, we want to use Metanorma syntax (or AsciiDoc for non-Metanorma users) because we will use this for model-based authoring (i.e. Metanorma will import the models and extract the text).

I don't mind allowing separation of relations for complex cases, but otherwise, it is much easier understood if the class relations are inside the definition -- e.g. superclass.

Remember we are trying to establish a syntax that fills in a Ruby model, then generate XMI or images. We can have multiple syntax options to fill in the same Ruby model.

[ronaldtse]

The separation of a Comment from Class syntax most certainly won't work if you have more than a few classes... won't want to give names to all of those Comments.

[ronaldtse]

Sample of same comment applying to two locations.

[DmitryDrobotov]

If it is possible to attach a comment to several elements we need to have its own notation like:

comment MyComment {
    ...
}

And then link comments to other model elements.

[ronaldtse]

@DmitryDrobotov yes. However, we should also provide a shorthand for comments that only applies to one entity:

1. It is annoying to make a separate "comment" entity.
2. It is annoying to have to uniquely name a "comment".

[w00lf]

@DmitryDrobotov yes. However, we should also provide a shorthand for comments that only applies to one entity:

1. It is annoying to make a separate "comment" entity.
2. It is annoying to have to uniquely name a "comment".

As a shorthand we can use something like //, example:

//This is a class for pets
class Pet {
   // name of the attribute, attribute comment
   + name
}

And combine this with comment notation, as @DmitryDrobotov mentioned, I like this idea.

[ronaldtse]

I think we should distinguish between "comment objects" and "non LutaML comments".

For non-LutaML comments, we should decide whether to use # or // as a comment prefix?

Perhaps we should use:

• // for non-LutaML comments (i.e. skipped by LutaML parsing)
• # for LutaML comments objects?

How about this?

// This is a comment that is not part of LutaML. This comment doesn't mean anything to LutaML.
// This is a second line comment. This comment doesn't mean anything to LutaML and will be skipped in parsing.

class Pet {
  # This is a comment for class Pet in LutaML
  # This is the second line of the same comment

  + name {
    # This is a comment for the Pet class in LutaML, split
    # into two lines but will be rendered as one.

    # This is a second comment object split into two 
    // This comment is not part of LutaML
    # lines. The // comment is skipped in LutaML parsing
  }
}

[ronaldtse]

Question: how do we differentiate class Pet vs enum Pet in references?

In fact, all the primary types: (Class, Object, Enum, Package, Relationship) need to be distinguished.

e.g. For attributes we have #{attribute name}.

class A
enum A {
  foo
  bar
}
comment MyComment {
  My comment
}

A -> MyComment // what does this "A" mean?
class A -> MyComment // or this?
[class] A -> MyComment // or this?
@A -> MyComment // or this?

enum A -> MyComment // or?
[enum] A -> MyComment // or?
...

[w00lf]

I think we should distinguish between "comment objects" and "non LutaML comments".

For non-LutaML comments, we should decide whether to use # or // as a comment prefix?

Perhaps we should use:

• // for non-LutaML comments (i.e. skipped by LutaML parsing)
• # for LutaML comments objects?

How about this?

// This is a comment that is not part of LutaML. This comment doesn't mean anything to LutaML.
// This is a second line comment. This comment doesn't mean anything to LutaML and will be skipped in parsing.

class Pet {
  # This is a comment for class Pet in LutaML
  # This is the second line of the same comment

  + name {
    # This is a comment for the Pet class in LutaML, split
    # into two lines but will be rendered as one.

    # This is a second comment object split into two 
    // This comment is not part of LutaML
    # lines. The // comment is skipped in LutaML parsing
  }
}

Sounds good, lets use # as display comments and \\ as code comments for lutaml file.

[w00lf]

Question: how do we differentiate class Pet vs enum Pet in references?

In fact, all the primary types: (Class, Object, Enum, Package, Relationship) need to be distinguished.

e.g. For attributes we have #{attribute name}.

class A
enum A {
  foo
  bar
}
comment MyComment {
  My comment
}

A -> MyComment // what does this "A" mean?
class A -> MyComment // or this?
[class] A -> MyComment // or this?
@A -> MyComment // or this?

enum A -> MyComment // or?
[enum] A -> MyComment // or?
...

Question: how do we differentiate class Pet vs enum Pet in references?

In fact, all the primary types: (Class, Object, Enum, Package, Relationship) need to be distinguished.

e.g. For attributes we have #{attribute name}.

class A
enum A {
  foo
  bar
}
comment MyComment {
  My comment
}

A -> MyComment // what does this "A" mean?
class A -> MyComment // or this?
[class] A -> MyComment // or this?
@A -> MyComment // or this?

enum A -> MyComment // or?
[enum] A -> MyComment // or?
...

We could use named alias:

class A as class_a
enum A as enum_a {
  foo
  bar
}
comment MyComment {
  My comment
}

class_a -> MyComment 
enum_a -> MyComment 

or we can introduce id attribute:

class A { 
  id class_a
}
enum A {
  id enum_a
  foo
  bar
}
comment MyComment {
  My comment
}

class_a -> MyComment 
enum_a -> MyComment 

[ronaldtse]

Sounds good, lets use # as display comments and \ as code comments for lutaml file.

Awesome! We have established a convention...

We could use named alias:

I like named alias. This looks nice:

class A as class_a
enum A as enum_a

Ping @opoudjis @DmitryDrobotov for thoughts too.

[w00lf]

Implemented