Comments in Functionblocks

[drehstromer]

Hi @klauer
I have continued testing blark and created a small documentation project.
Firstly, I have to say that I find it very impressive how you have built this piece of software. I'm still on a steep learning curve with Python, but I think I'm getting the hang of it. At least its enough to slowly understand this codebase. 😅
I have a question with the comment parsing.
I have the following FB declaration:

FUNCTION_BLOCK FB_EventHandler EXTENDS FB_Handler // Comment Number 1
// Comment Number 2
(*
Comment Number 3
Comment Number 4
*)
VAR_OUTPUT
	bDebug:			BOOL;
	bInfo:			BOOL;
	bWarning:		BOOL;
	bError:			BOOL;
END_VAR
VAR
	nLength:		INT;
	aEvents:		ARRAY [0..100] OF ST_Event;
	nIndex: 		INT;
END_VAR 

If i make a summary of this functionblock, i can access its comments with FB_Eventhandler.Comments[] but there is "only" comment "Comment Number 1" in this array. Where are the other comments stored?

Thanks for your reply
drehstromer

[drehstromer]

@engineerjoe440 do you know something about this topic?

[engineerjoe440]

Hi @drehstromer! Unfortunately, I don't have the code pulled up in front of me, at the moment. I'll have to dig in and take a look. I suspect that subsequent comments are getting parsed into another block of the nested structures.

[klauer]

Hi @drehstromer, thanks for the praise about blark! Apologies about the long delay in my reply - I didn't have a personal laptop to do any open source work since starting a new role last year.

I'm not sure if you still would like to see this resolved, given how old your comment is.

For your issue, it's a bug (or being a bit more charitable to myself, an oversight?). Those comments are not currently accessible in the summary objects, as you've found. It requires a bit more digging into the full Python representations.

Finding the comments

import blark
from blark.summary import CodeSummary

code = """
FUNCTION_BLOCK FB_EventHandler EXTENDS FB_Handler // Comment Number 1
// Comment Number 2
(*
Comment Number 3
Comment Number 4
*)
VAR_OUTPUT
	bDebug:			BOOL;
	bInfo:			BOOL;
	bWarning:		BOOL;
	bError:			BOOL;
END_VAR
VAR
	nLength:		INT;
	aEvents:		ARRAY [0..100] OF ST_Event;
	nIndex: 		INT;
END_VAR 
END_FUNCTION_BLOCK
"""

parsed = blark.parse_source_code(code)
summary = CodeSummary.from_parse_results(parsed)

print("Function block comment:", summary.function_blocks["FB_EventHandler"].comments)

fb = summary.function_blocks["FB_EventHandler"].item
print("Associated function block parsed object", type(fb))

print("The VAR declaration block has the remainder of the comments:")
print(fb.declarations[0].meta.comments)

Running this results in the following output:

Function block comment: [Token('SINGLE_LINE_COMMENT', '// Comment Number 1')]
Associated function block parsed object <class 'blark.transform.FunctionBlock'>
The VAR declaration block has the remainder of the comments:
[Token('SINGLE_LINE_COMMENT', '// Comment Number 2'), Token('MULTI_LINE_COMMENT', '(*\n    Comment Number 3\n    Comment Number 4\n*)')]

But why?

Why is this the case - and why isn't it associated with the function_block object itself?

Well, blark's algorithm for aggregating comments and associating them with some syntax tree element favors the closest element that:

1. Isn't on a line after the comment
2. Is "worthy" of holding a comment

The reason the comments found their way into the VAR block above is due to reason (1). The first comment is assumed to be relevant since it's on the same line, whereas the remaining comments have to wait for the next one.

The objects "worthy" of holding comments are larger things like function blocks, variable declaration blocks, individual variable declarations, interfaces, actions, statements, if/else, etc - and not things like arithmetic or constants.

At least on the team I used to work with, we tended to put comments before things such as FUNCTION_BLOCK. I'm not sure of the prevalence of other commenting/documenting styles, to be honest.

Path forward

At the very least, the summary objects should have some better way of tracking the declaration block comments.

In the short term (11 months later?), you could use the trick above if your code is consistently structured as such.