Add an event/notification when a function definition begins

[rdw-software]

Hello! I've toyed around with the parser for a bit, and as I was trying to detect function definitions after block comments (for a doc comment style API documentation) I noticed that only the end of the function definition is currently passed (via onNodeCreated).

This leads to an issue where I'm getting intermediate comments that are inside the function body as part of the doc comment, because the event is triggered after the entire block has been parsed. Example:

--- Function description starts here.
-- @param something This should apply to the below function
function MyModule:DoSomething(something)
	-- This comment triggers onNodeCreated before the function definition does
	return "Test"
end
-- This is where the function definition triggers onNodeCreated

In this scenario, I want to associate the doc comment before the function with the function itself, but the inner comment must not be considered as part of the doc comment. I tried to do this by simply tracking comment > function definition in that order, but it fails because the function definition comes "too late" for this approach to work.

So far, I've managed to hack in a notification by modifying parseFunctionDeclaration, like so:

  function parseFunctionDeclaration(name, isLocal) {
    var flowContext = makeFlowContext();
    flowContext.pushScope();

    var parameters = [];
    expect('(');
    console.log("BEEP BOP! Function definition begins here!"); // Seems to always be triggered during the function definition, so it should be the right place?
    if (options.onCreateFunctionDefinition) options.onCreateFunctionDefinition(ast.functionStatement(name, null, isLocal, null));
    // Fake event notification (the null parameters aren't available yet since the function definition isn't yet complete)

    // The declaration has arguments
    if (!consume(')')) {
<snip>

Is this a use case that could be supported "officially" so that I can just install via npm instead of hijacking the module code? Also I doubt this is a great way to solve the problem, but I don't know the code well enough to come up with a better design.

Any ideas are appreciated! Thank you for your time.