Documentation/Comment Blocks

[mediatech15 (Kyle Mason)]

About

Collection of block with little to no function. That is their purpose. These blocks allow you to annotate or comment your blocky scripts. The blocks are converted to actual comments in code. The nice feature of these are not needing to use throw away variables, extra logging blocks, etc. Is under the Library Docs/Comments

Do note that blockly does support comments and this isn’t providing something new but more of another way to do it. I personally don’t like blockly popovers. See Post #3

All of my (Kyle Mason) (mediatech15) blocks are free to copy modify and edit how you see fit. You may re-post the variants freely (an inspired by is nice)

Blocks

Comment

Contains both Free Floating comments (Left) and chain-able comments (Right).

Note

Contains both Free Floating notes (Left) and chain-able notes (Right).

Document

Contains both Free Floating documents (Left) and chain-able documents (Right).

IMPORTANT

Contains both Free Floating importants (Left) and chain-able importants (Right).

Bare

Contains both Free Floating bare comments (Left) and chain-able bare comments (Right).

Changelog

Version 1.0

• initial release

Version 1.1

• Bugfix big thanks to rafael_09 for the code mods
• Sorry for the delay a newborn (our first) will really take up your time

Version 1.2

• Fixed newline issue

Resources

latest

Gitlab Snippet (RAW)

v1.2

Gitlab Snippet

v1.1

Gitlab Snippet

v1.0

Gitlab Snippet

[rlkoshak (Rich Koshak)]

I just wanted to add a note that Blockly already supports adding comments as a property on a block. Right click on the block, choose add comment and

You can show and hid the comment as desired. But the above lets you create always visible comment blocks which is different. I just didn’t want people to think that this library exists because comments in general are not supported.

[mediatech15 (Kyle Mason)]

Correct and I am aware of that. The popups in blockly to me are well… cumbersome. I personally much prefer to see comments inline (like code) given blockly is only replacing/inserting code. Given the blocks in this are only adding JS comments there is zero harm in functionality. As with everything there are many ways to do something.

I made this based on my personal preferences and the dislike of the built in solution. May not be for everyone but it also isnt harmful (unless there is something I am not aware of in the JS parser).

@rlkoshak

I just didn’t want people to think that this library exists because comments in general are not supported.

I agree with this statement I can clarify that in the original post. It isn’t because of lack of support but more of another way to do it based on personal/development preferences.

[ysc (Yannick Schaus)]

Another note: you can disable a block with the contextual menu as well, it will then appear in gray/brownish and won’t output any code, like so (see the “log” block color)

If you ever want the rule to actually log the message you can simply reenable it.
But those comment blocks are nonetheless valuable!

[mediatech15 (Kyle Mason)]

Sure and that is useful for things you may log or may not. I think of the enable disable button in node-red on their debug block. This was also incase someone would ever want to copy the actual JS code. This would have normal inline comments.

[Robin_Emde]

Hi,
I personally like the idea, but having used these blocks I found one or two problems:

1. No matter which type I used (Comment, Document, Note), when I snapped it before my first rule line (variable) the line got disabled/commented out. It seems there is a Carriage Return/LF missing at the end.

//Variables:thing_tts_speaker = 'sonos:PLAY1:RINCON_123F3F45F8F123456';
item_mediacontrol = 'SonosPlay1_MediaControl';

2. The block width is limited. Longer comments/notes do not fit into the block and are not readable in full length. The text field has no multi-line support. Putting together multi-line comments needs multiple blocks?

Maybe I am doing something wrong here with using the blocks, but problem 1 was a bit irritating.
For commenting my rules (line by line) I am using the snapping blocks, of course. (To be clear: That does not mean that I comment EVERY single line in my rules )

[GeWaLu (Georges)]

Commenting is a good practice, so I like the concept, which is a good addition to the built-in commenting feature, but I am unfortunately also affected by the issue of the missing newline described in the previous comment causing the risk to comment out some functional code
I exprimented by creating a copy and adding a newline on each template line like the following example

      template: "//{{field:TEXT1}}\n"  

This solved the issue and each block gets a own line. While looking once more at the template I noticed that openhab saved this silently as

  template: >
    //{{field:TEXT1}}

The result is the same. It now honors the newline. So it may be worthwhile to check in a future version if this extra “>” is neeeded to make the library more robust and make sure that blockly always honors the newline

[tophee (Chris)]

@Robin_Emde

No matter which type I used (Comment, Document, Note), when I snapped it before my first rule line (variable) the line got disabled/commented out. It seems there is a Carriage Return/LF missing at the end.

Isn’t this a bug which should be fixed (or at least warn people about the issue)?

I have been sitting for hours debugging some blockly scripts until I realized that the problem was with the comment blocks…

[mediatech15 (Kyle Mason)]

Sorry I’ve been busy with a newborn. I’ll try and find some time soon to fix it and release a new version

[mediatech15 (Kyle Mason)]

Attention all v1.1 is posted

Version 1.1

• Bugfix big thanks to rafael_09 for the code mods
• Sorry for the delay a newborn (our first) will really take up your time

Again a BIG thanks to everyone using this and the support of this lib along with those that went out to test things and provide workarounds for those using this.

[Mark_VG (Mark)]

Please can you confirm if the issue with comment blocks removing next line of code?

I downloaded the library todsy and then also doent s few hours debugging code thst was correct but affected by the first comment.

[mediatech15 (Kyle Mason)]

@Mark_VG

Please can you confirm if the issue with comment blocks removing next line of code?

I downloaded the library todsy and then also doent s few hours debugging code thst was correct but affected by the first comment.

Can you post a pic of the exact block order you are using so I can test it?

[Mark_VG (Mark)]

@mediatech15

Can you post a pic of the exact block order you are using so I can test it?

Hi. Yes, I am using the simple rule as follows:

This generates:

var Test;


//My Comment to Test that next line gets "lost"Test = 'My Test Value';
console.error(('Test Value is: ' + String(Test)));

Which I believe should be:

var Test;


//My Comment to Test that next line gets "lost"
Test = 'My Test Value';
console.error(('Test Value is: ' + String(Test)));

This set does work:

var Test;


Test = 'My Test Value';
console.error(('Test Value is: ' + String(Test)));

Thanks
EDIT:

@GeWaLu

template: "//{{field:TEXT1}}\n"

I manually made these changes which seems to have helped, so maybe they need to be applied to the published version?

[mediatech15 (Kyle Mason)]

@Mark_VG

I manually made these changes which seems to have helped, so maybe they need to be applied to the published version?

seeing that helps I will double check it is possible I missed an update needed in this last revision. Stay tuned

[mediatech15 (Kyle Mason)]

The latest version has the fix for your issue. Thanks for reporting.