Closed ronaldtse closed 3 years ago
We also need to think about:
@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?
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.
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.
Sample of same comment applying to two locations.
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.
@DmitryDrobotov yes. However, we should also provide a shorthand for comments that only applies to one entity:
@DmitryDrobotov yes. However, we should also provide a shorthand for comments that only applies to one entity:
- It is annoying to make a separate "comment" entity.
- 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.
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
}
}
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?
...
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.
Question: how do we differentiate
class Pet
vsenum 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
vsenum 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
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.
Implemented
Proposal:
Alternative: