Add more standard line comments

Question

Hi,

would it be possible to get line comments which are more common standard ('//' or '#'') ? The reason I am asking is because I use PlantUML a lot  I created tons of macro code, turning it into some kind of DSL already. Therefore I also have to document all these macros, for which I use AsciiDoctor. AsciiDoctor has this handy feature which allows to include external source code files as code listings (even partially) which then can be further described in the AsciiDoc. When the source code changes, you do not have to update the AsciiDoc part, where the code listing is displayed. Even better, one can also use callout icons referencing specific lines in the source code.

You can even assign callout numbers directly in the source code (via one of the recognized inline comment styles) and then refer to these callout numbers in the AsciiDoc. Asciidoctor renders these callout number nicely in its own part of the document but will fail to do so in the included PlantUML source code listing, because PlantUML does not use standard line comments.

 

Currently I do have to do something like this in my PlantUML code:

@startuml
!include ../arc42Styles-2.0.0.puml

makeComp("DoDi", "SV-4955", "SV4955", "system", "QCAT_INFRASTRUCTURE")
makeComp("EA Online", "IS-4821", "IS4821", "system", "QCAT_PRESENTATION")
makeComp("MyOtherClient", "IS-9944", "IS9944", "system", "QCAT_FUNCTION")

makeIF("Archivierung", "IF0001", "provided")    /'<1>'/

SV4955 -r- IF0001   /'<2>'/

IS4821 useIF("IF0001", "IF-4969", "REST", "l")    /'<3>'/
IS9944 useIF("IF0001", "IF-1234", "REST", "u")

@enduml

Given these non-standard inline comments (I know they are actually block comments, but PlantUML will not allow me to do it any other way), Asciidoctor is not able to replace these with its nice callout icons.

Thanks and regards,

Christian

 

 

 

 

Answer 1

We are facing several limitations.

First, we really cannot use # for comments, because # is used in many other syntax context, and our parser will really get lost.

We have intentionally choosen non-standard delimitor for comments (that is /' and '/ ) because we wanted PlantUML diagram to be included in C/Java/C++/C# source code, and we did not want the C/Java/C++/C# compiler to be confuse with PlantUML comment delimitor.

Now, we could add new comment delimitors, but we have limited options.

For example, we cannot use // as delimitor, because it will break the following diagram:

@startuml
Bob -// Alice : hello
@enduml

http://www.plantuml.com/plantuml/uml/SoWkIImgAStDuNBAJrBGrTTNSCp9J4vLi5B8ICt9oUToICrB0Se20000

A simpler idea : you can put an Asciidoctor comment into a PlantUML comment. For example you may be interested by the following diagram, that is currently working for PlantUML:

@startuml
!include ../arc42Styles-2.0.0.puml

makeComp("DoDi", "SV-4955", "SV4955", "system", "QCAT_INFRASTRUCTURE")
makeComp("EA Online", "IS-4821", "IS4821", "system", "QCAT_PRESENTATION")
makeComp("MyOtherClient", "IS-9944", "IS9944", "system", "QCAT_FUNCTION")

'// <1>
makeIF("Archivierung", "IF0001", "provided")

'// <2>
SV4955 -r- IF0001

IS4821 useIF("IF0001", "IF-4969", "REST", "l") /'/* <3> */'/
IS9944 useIF("IF0001", "IF-1234", "REST", "u")

@enduml

Does is sound like a possible workaround for you ?

And finally we could contact AsciiDoctor authors and ask them if they would accept to recognize /' and '/ as standard comment delimitors.

Comments

Many thanks for your immediate reply!

Your solutions (1) and (2) work. They do leave a ' in font of the callout number, which is no problem, but they also require a separate line in the source code which does not look that nice in my docs but still better than /'<3>'/.

Definitely a useful workaround but as you suggested - well if you accidentally happen to talk to the AsciiDoctor developers ...  ;-)