Update YW comments in example.py in main/resources

[swanskysong]

I think how to "workflow-ize" this example is not clear (at least some part of it), I'll take a look to see how to come up with a valid test case

[tmcphillips]

I just committed some changes to the comments in example.py. Just playing with possibilities. Please go ahead with further changes.

[swanskysong]

changes: 1) use name aliasing to distinguish modified variables (e.g., are both input and output of a block) and to explain what variables stands for, 2) remove the for loop as the requirement of no block within branching and looping, 3) modified the code itself

Issues: 1) when a variable is created as the reference to a input file, what is the input of this block? I proposed to use "@in file_name @as description", but this is may not be consistent with other comment structure. Or we can simply say "no input to this block". 2) we have the following structure:

'pound sign' 'pound sign' name... 'pound sign' @in... 'pound sign' @out... ?

We need to use a special syntax to end this comment structure, maybe a "##" as a new line to the end? It's possible the next line is an actual comment for the code which makes it (though not impossible) different for the parser to understand

[tmcphillips]

The updated comments in the script look great. I like the name aliasing with @as, and the approach of using double quotes to indicate that one is referring to a string literal (rather than a variable) in an @in comment.

[sycao5]

Hello Tianhong and Tim,

I read the updated comments which are organized and clear. I am packing recently. I would like to ask one question. For the comment such as

@begin standardize_with_mask

@in data @as NEE_data

@in mask @as land_water_mask

@out data @as standardized_NEE_data

How to represent the “data” and “NEE_data” in the graphical representation? To me, “data” is a variable and “NEE_data” is a value of the “data”. Will it be useful to represent “data” and “mask” differently if “data” is a common input type and “mask” is a user-defined (or specific) input type?

Thanks and regards,

Yang

On Dec 22, 2014, at 9:11 PM, Timothy McPhillips notifications@github.com wrote:

The updated comments in the script look great. I like the name aliasing with @as https://github.com/as, and the approach of using double quotes to indicate that one is referring to a string literal (rather than a variable) in an @in https://github.com/in comment.

— Reply to this email directly or view it on GitHub https://github.com/yesworkflow-org/yw-prototypes/issues/4#issuecomment-67915153.

[csjx]

@swanskysong For defining a code block, we discussed using:

# [[ standardize_with_mask
# ... directives go here ...
... code goes here ...
# standardize_with_mask ]]

We had decided that the endCodeBlock could be optional, but from a pragmatic perspective, it'd be a lot easier to have it (for parsing the blocks).

1) Are you proposing that # @begin should be the beginCodeBlock delimiter? 2) I'm assuming that when you write @in file_name @as description you mean @in file_name @as aliasName (meaning that there can be a single-word variable alias that better describes the data variable). I ask this because we also planned to allow for an optional description of a variable, like:

# @in data @as NEE_data - Net Ecosystem Exchange data

I've updated the vocabulary EBNF to accommodate these new features. Let's get consensus on the @begin directive versus the #[[ ... #]] syntax.

[csjx]

@sycao5 The # @in data @as NEE_data syntax you referred to is how we discussed aliasing a variable name with a more readable, single-word variable name. For instance, # @in n @as net_ecosystem_exchange (since n is a really short and vague variable name). We might want to replace @as with @label or @means or something like that to make it clear that we're giving the @in variable a better label.

[csjx]

I see that ## is the Doxygen begin delimiter for documenting a function or class, so it makes sense to build on top of that. If we used ## to end a codeBlock, though, it might look like the beginning of a new codeBlock. Since we're not planning to support recursion right away, do we have to have an endCodeBlock delimiter (and just assume the next beginCodeBlock delimiter ends the previous (or an EOF)?

[tmcphillips]

I introduced the @begin/@end syntax when playing around with the comments in example.py. It seemed a bit easier to spot in the code than the [[ and ]] and more obviously associated with the other comments with tags that start with @, but either is fine with me for now. I suggest we continue experimenting--what works best may be clearer once we have a large number of examples (including artificial examples for exercising each feature) to look at and when we get feedback from users.

[csjx]

Man, we seem to be reinventing the wheel when it comes to DOxygen. Notice that the @param directive includes an optional direction attribute that can have values of [in], [in, out], or [out].

[ludaesch]

@csjx FYI ... I might be wrong, but I think I might have introduced the funny "[[" and "]]" at the pool-side (or just before), hanging out with Paolo. If that's the case, it means I never gave the actual syntax much thought at the time (about 3 seconds maybe). So I'm happy to see this evolving into something usable..

[csjx]

I think I'm also preferring the @begin codeBlockName and @end codeBlockName directives for defining code blocks too. It's more in line with our other directives, and yeah, like Tim said, it seems easier to spot in the code. +1.

[tmcphillips]

I added aliases to the @in and @out comments for the top-level main function in example.py. These match the aliases of @in and @out comments for the blocks within main so that channels can be inferred between the outer 'ports' of the 'workflow' and the ports on the 'programs' within the workflow.