search

pasa / asdl-rs

Apache License 2.0
10 stars 1 forks source link

Doc comments #6

Closed matklad closed 5 years ago

matklad commented 5 years ago

it would be cool to add doc-comment syntax to ASDL, which can be copied into documentation comments in the generated code. Not sure if ASDL supports doc (or even plain) comments at all...

pasa commented 5 years ago

it would be cool to add doc-comment syntax to ASDL, which can be copied into documentation comments in the generated code. Not sure if ASDL supports doc (or even plain) comments at all...

Yeh. Asdl do not mention about comments anything. It's not a problem to add comments to types. I wonder how to implement it for SumType constructors to make it more redable. Assume we have this SumType

field = Required(typeId, id?)
    | Optional(typeId, id?)
    | Repeated(typeId, id?)

The most obvious way to add comments is like this one

//Some comment for field
field = 
    // Some comment for Required
    Required(typeId, id?)
    | 
    // Some comment for Optional
    Optional(typeId, id?)
    |
    // Some comment for Repeated
    Repeated(typeId, id?)

Looks alittle noisy. | on each line is a waste of space. We can move them to previous line. like this

//Some comment for field
field = 
    // Some comment for Required
    Required(typeId, id?) | 
    // Some comment for Optional
    Optional(typeId, id?) |
    // Some comment for Repeated
    Repeated(typeId, id?)

Another way is to support only one line comment for constructors like this:

//Some comment for field
field = 
    Required(typeId, id?)    // Some comment for Required
    | Optional(typeId, id?)  // Some comment for Optional
    | Repeated(typeId, id?)  // Some comment for Repeated

Looks more clean but no multiline.

Even more exotic way is to place it like this

//Some comment for field
field = 
    // Some comment for Required
    // Some line 2
    Required(typeId, id?)
    // Some comment for Optional
    // Some line 2
    | Optional(typeId, id?)
    // Some comment for Repeated
    | Repeated(typeId, id?)

Looks more readable but has a strange (logically) placement.

I need a view from the outside to make a choice.

pasa commented 5 years ago

I've implemented first case here e42c9ebb24c80a607eb15a46112c4400fb783f1a