C# support and method annotation parsing

[tim-slater-gt]

First I wanted to say a big thank you for sharing this working grammar for PeopleCode!

I have started to leverage this for a utility much along the lines of your PPC Analyzer, but with additional focus on enabling some refactorings, specific to this pull request is the ability to rename certain program-local elements like local variables or parameter names.

To support renaming parameter names I needed to have the

/+ &param as type +/ 

annotations that Application Designer places below method implementations in the AST so I tweaked the grammar to support this.

While not strictly required since Application Designer will update the annotations upon saving, it sure does feel nicer having them renamed as part of the refactoring process.

[lbaca]

Hi @tim-slater-gt,

I'm glad you found some value in this modest parser of mine, and I find your use-case to be very interesting. As you well stated, these "slash-plus" annotations would be regenerated upon compiling/saving in Application Designer. Being a form of comments themselves, I wouldn't feel too comfortable having them in the default token channel, as it injects "noise" in a way that goes against the stated goals of the project:

• To analyze PeopleCode
• To enable the validation of coding standards
• To use specially-formatted comments to enable the Javadoc-like AppClassDoc application

These automatically added annotations play no role in PeopleCode analysis, are outside the jurisdiction of coding standards (by being unmodifiable), and are alien to the AppClassDoc use-case or anything of the sort.

That being said, I very much like your refactoring use-case, and I see value in enabling this possibility. After all, the more readable code is, the higher quality in can be said to have. If someone reads your refactored code before it goes through App Designer, and sees that the arguments used in a method have one name but the slash-plus annotations say another, it leads to great confusion. By that same token (no pun intended), ordinary comments of any other sort (REMs, slash-stars, angle-bracket-stars) are also a fundamental part of the code under review, which means that refactored code should and must retain its comments. Of course, we're not going to emit those types of comments on the default token channel, nor do I think the slash-plus ones should be, either.

What I propose, therefore, is that the COMMENTS channel (see the parser implementation notes) be divided into two by "rerouting" slash-plus comments into their own channel (say, METHOD_SIGNATURE_ANNOTATIONS). This can be achieved by simply modifying this line for Java and this line for Python. Then, applications that use this parser could implement strategies such as those described here and here. I have an example of my own in AppClassDoc.

Once you have the slash-plus comments in their own channel, you can try to parse them with regular expressions. If you want to imbue the structure of slash-plus comments with syntax and semantic meaning like you do here, I don't necessarily see an issue. However, I think you should also provide an "escape hatch" such that the text between "/+" and "+/" could also be any random gibberish. That will never occur in PeopleCode compiled in App Designer, but it's one fewer assumption to accrue as technical debt.

Let me know your thoughts.

[tim-slater-gt]

Thank you for taking the time to reply. I fully recognize that these parser changes may not be needed for the project's stated goals, but I felt that since this is the most complete ANTLR grammar for PeopleCode it may be worth extending to add support for the method annotations.

I want to point out however that /+ +/ comments are not general block comments, you cannot use them in your code as a commenting mechanism like you can /* / and < *>. if you try to, they get deleted upon save. so I don't think there's worry/concern over these comments containing gibberish. they are well formed as part of the save process and should be safe to parse.

If you don't want to accept these changes that is perfectly fine and understandable due to them not really being needed for your stated goals/projects, but I wanted to offer them up 1.) as a way to show you that someone is leveraging your work :) and 2.) as a way to get in contact and say thank you! The grammar you built has been a very important piece for what our project can now do with App Designer.

Our project should go live (open source here on GitHub) later this month and we will happily maintain these changes there :)

[tim-slater-gt]

I've also pushed a couple of updates to my repo to add support for the "extends" annotation as well as how for a parameter of "array of array of string", the method annotation will say "Array2 of string".

[tim-slater-gt]

@lbaca in case you wanted to see what your parsing grammar has allowed to exist, the podcast of me demoing this went live today :) https://www.youtube.com/watch?v=w5nbiNPKHjI