search

david284 / ModuleDescriptor

VLCB/CBUS Module descriptor format & examples
0 stars 2 forks source link

Unattached comment in CANLEVER #10

Closed RichardCrawshaw closed 6 months ago

RichardCrawshaw commented 6 months ago

There is a comment element in the CANLEVER file that has no accompanying elements. It is the last element in the "nodeVariables" array, and is just { "comment": "end of node variables" } without any "type" element. This in turn trips up subsequent processing as the type is unknown.

While it would be easy to simply ignore any nodeVariable or eventVariable elements that don't have a known type, this will also fail to alert to those elements that have an incorrect type value. If it is wanted to be able to include a comment in those arrays then a type with a specific value (say "comment") would enable this while also allowing alerting to other typos.

david284 commented 6 months ago

My understanding (maybe too simplistic) of the benefits of using a 'self documenting' type of file like json is that the processing application would pick out the keys that it's looking for, and ignore any that it isn't This does lead to the question about what is "incorrect" - in this scenario an unexpected key or value is not necessarily 'incorrect' Yes, I would agree it means it then won't find any "incorrect" keys or values - but in my opinion to try to do so does constrain the flexibility of the use of json (or any other self documenting format) Apologies if I've misunderstood the issue

I do mention the use of comments in the document There is no direct support for comments, but a key-value pair can be used where necessary E.g. “comment”:”comment added for clarity” But I haven't explicitly made it a specific 'type'

RichardCrawshaw commented 6 months ago

The key in question is claiming to be a NodeVariable, which it isn't. The problem is that it isn't easily possible to determine this; a large amount of extra processing is needed. Just checking for this particular instance is relatively straightforward, but doing so infers that similar checking is to be done for other cases, which becomes increasingly complex and error prone in its own right.

The deserialisation process uses a standard JSON serialization library that knows nothing of what might or might not be expected. As for selecting which keys are wanted, it is easy to provide to the serialiser an object that, say, does not include a comment property. In which case there will be no comments loaded. But here, we have a NodeVariable field, which has none of the standard node variable properties.

The suggestion of having a type for comment was to enable a comment within a NodeVariable (or EventVariable) array.