Introduce custom JavaDoc tags #565

[onewhl]

Description

Introduce custom JavaDoc tags to make generated code comments structured.

@utbot.classUnderTest - Inline link to the enclosing class.
@utbot.methodUnderTest - Inline link to the method we test.
@utbot.expectedResult - Value we expect to get.
@utbot.actualResult - Value we got.
@utbot.executes - Executed condition.
@utbot.invokes - Invoked method.
@utbot.returnsFrom - Statement we return from.
@utbot.throwsException - Thrown exception.

The list of tags could be expanded

• Implemented JavadocTagInfo to introduce our custom JavaDoc tags.
• Implemented CustomJavadocTagProvider and registered it in plugin.xml to support plugin's custom tags.
• Overrided behavior of JavaDocumentationProvider#generateRenderedDoc and registered it in plugin.xml to render our custom JavaDoc tags correctly.
• Added a flag useCustomJavaDocTags to UtSettings.
• Added integration tests.

We show only tags that have some non-null value. After plugin's removal, IDE doesn't recognize our custom tags. It doesn't lead to errors, but highlights tags with yellow color.

TODO: Add a test in the intellij module in separate PR
TODO: @amandelpie suggested to add a tag for display name in (PR-624) in case of JUnit4 in separate PR.
TODO: After upgrading to 2022.1 fix comment rendering in separate PR by using default JavaDocInfoGenerator.

Fixes #565

Type of Change

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

Automated Testing

Run tests SummaryConditionsTest, SummaryMinStackTest, SummaryExceptionClusteringExamplesTest.

Manual Scenario

Set useFuzzing = false and useCustomJavaDocTags=true in UtSettings.

Case 1: check that tags are supported and shown in IDE.

1. Open any Java project in IntelliJ IDEA.
2. Add JavaDoc comment above any method and start typing @utbot -> you will notice that completion works and our custom tags are shown.
3. You can also render comment clicking toggle on the right side of the comment.

Case 2: check that the plugin generates comments using custom tags.

1. Open any Java project in IntelliJ IDEA
2. Click on any class/method and select Create tests with UTBot action
3. Check the comments under generated tests.

Tested using runIde command.

Checklist (remove irrelevant options):

• The change followed the style guidelines of the UTBot project
• Self-review of the code is passed
• The change contains enough commentaries, particularly in hard-to-understand areas
• New documentation is provided or existed one is altered
• No new warnings
• New tests have been added
• All tests pass locally with my changes

[onewhl]

I would like to discuss several things.

• Is it OK to change global settings from UtSettings in tests (see SummaryTestCaseGeneratorTest)? The order of tests is non-determined, it seems it possible could lead to errors. I used JUnit extension to avoid it.
• Is it possible to show error message in CI logs in case test fail?

[Damtev]

I would like to discuss several things.

• Is it OK to change global settings from UtSettings in tests (see SummaryTestCaseGeneratorTest)? The order of tests is non-determined, it seems it possible could lead to errors. I used JUnit extension to avoid it.
• Is it possible to show error message in CI logs in case test fail?

1. Mostly it is not OK, just because of your mentioned, reasons, so we use a lot of util functions that change them only for specific tests. You can see some examples in the org.utbot.examples.UtValueTestCaseChecker file, like withoutMinimization and others. But I suppose your way is acceptable too.
2. I am not sure about common logs, but we publish some artifacts after a pipeline ending, that you can find in the pipeline summary tab. One of them is utbot_framework_logs, which is a simple gradle tests report. In this report, you can find logs and, most importantly, test output for each test.

[amandelpie]

Please make some minor changes

The most part of requirements were implemented