Annotations on function definitions and function calls

[tmcphillips]

YW currently expects nested code blocks to be defined in-line, whereas many scripts are structured as functions (or classes) with a top-level script that calls these functions (or methods on objects). This is a proposal to allow YW users to model function calls as nested code blocks:

Allow function definitions to be marked up with YW comments.

• These blocks will delimited by @begin and @end comments like other blocks. The name following the @begin keyword is expected to match the name of the function.
• An @as qualification a code block will allow an alias to be used to refer to the function in YW annotations on calling code.
• Function definition blocks will not support @in or @out comments. Instead users will employ @param and @return comments (compatible with Javadoc, Doxygen, etc).
• @as qualifications on the @param and @return comments optionally will provide aliases that may be used by annotations on calling code.

Allow calling code to be marked up as a YW code block.

• A @calls comment within the block will name the function called.
• A @binds comment will qualify each @in, @param, or @out annotation that supplies data to or receives data from the function. Each @binds comment will name the corresponding function parameter or return value.

Each function call-definition pair will be represented by YW-Model and YW-Graph as a single code block. If a function includes code blocks (or calls other functions) marked up with YW comments, the former will be represented as a sub-workflow with the latter as its component programs.

[ludaesch]

On Thu, Feb 5, 2015 at 9:21 PM, Timothy McPhillips <notifications@github.com

wrote:

...

• Function definition blocks will not support @in or @out comments. Instead users will employ @param and @return comments (compatible with Javadoc, Doxygen, etc).

I like that. This way you get both: a form of backwards compatibility with Javadoc etc, but also a distinction what is a block with @in and @out (part of the dataflow model) and what are function parameters and return values - different beasts!

Will be interesting to think about visualizing the new, enriched model!

-

• @as qualifications on the @param and @return comments optionally will provide aliases that may be used by annotations on calling code.

Allow calling code to be marked up as a YW code block.

• A @calls comment within the block will name the function called.
  • A @binds comment will qualify each @in, @param, or @out annotation that supplies data to or receives data from the function. Each @binds comment will name the corresponding function parameter or return value.

Yep. Will need something like that to keep track of the dataflow..

Each function call-definition pair will be represented by YW-Model and YW-Graph as a single code block. If a function includes code blocks (or calls other functions) marked up with YW comments, the former will be represented as a sub]workflow with the latter as its component programs.

Seems reasonable as well

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

[sycao5]

When a function definition block is met during parsing, how to find the file containing this function definition?