Comments for variables show up in a wrong order

[Philipp1297]

I noticed when building the documentation that the comments are in a wrong order.

The given Code Sample:

// Analog input value
iAnalogValue AT %I* : INT;

// Config data for analog input scaling
stScalingConfig : ST_ANALOG_IO_CONFIG;

// Config data for warning and error levels
stEWConfig : ST_ANALOG_EW_LEVELS;

// Config data for warning and error levels delay times
stEWDelayConfig : ST_ANALOG_EW_DELAYS;

This will output the documentation like this:

Is there a way to make this work, without having to reorder my comments for multiple projects?

It would make sense to allow comments above, below and in the same row

[RobertoRoos]

Thanks for raising an interesting point.

TwinCAT has a sort of official commenting style too, and I think it's important to stick with it. You can see this in two ways:

1. TwinCAT is also starting to support reStructuredText and in their examples they put variable comments inline: https://infosys.beckhoff.com/english.php?content=../content/1033/tc3_plc_intro/6158080011.html&id=8022103526872950709
2. After compiling a PLC project you can see any comments in the online view. These comments are also available over ADS actually.

So for point 1 inline comments are used.

For point 2 inline comments are preferred, but comments above are taken as a fallback. I just checked with the following:

It shows as:

For plcdoc we could do the same: prefer an inline comment but show an above-comment when there is no inline one. But this will make our grammar very tricky, mostly because newlines are ignored by default. So we'd have to make some finicky rules to match an above-comment but only if it doesn't belong to another line already.

Frankly, I don't think I'll do anything with this any time soon. Maybe when we move away from TextX and get more powerful parsing this could be improved.

[Philipp1297]

Switching to Lexer might be a good option at this stage. Initially, I was considering building it from scratch using Lexer, but during my research, I came across your repository.