Add descriptions for special input parameters in Configuration Docs (#1423)

* Add descriptions for special Input parameters

* Add javadocs for new attribute

Author: aaronweissler

components/inspectit-ocelot-configdocsgenerator/src/main/java/inspectit/ocelot/configdocsgenerator/ConfigDocsGenerator.java

@@ -21,6 +21,8 @@
 import java.io.IOException;
 import java.lang.reflect.Field;
 import java.util.*;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
 import java.util.stream.Collectors;
 
 /**
@@ -29,6 +31,26 @@
  */
 public class ConfigDocsGenerator {
 
+    /**
+     * Map of descriptions for special input parameters.
+     */
+    Map<String, String> specialInputDescriptions = new HashMap<String, String>() {{
+        put("_methodName", "The name of the instrumented method within which this action is getting executed.");
+        put("_class", "The class declaring the instrumented method within which this action is getting executed.");
+        put("_parameterTypes", "The types of the parameters which the instrumented method declares for which the action is executed.");
+        put("_this", "The this-instance in the context of the instrumented method within which this action is getting executed.");
+        put("_args", "The arguments with which the instrumented method was called within which this action is getting executed. The arguments are boxed if necessary and packed into an array.");
+        put("_returnValue", "The value returned by the instrumented method within which this action is getting executed. If the method terminated with an exception or the action is executed in the entry phase this is null.");
+        put("_thrown", "The exception thrown by the instrumented method within which this action is getting executed. If the method returned normally or the action is executed in the entry phase this is null.");
+        put("_context", "Gives direct read and write access to the current context. Can be used to implement custom data propagation.");
+        put("_attachments", "Allows you to attach values to objects instead of to the control flow, as done via _context.");
+    }};
+
+    /**
+     * Map of descriptions for special input parameters that can have different names matching a regex.
+     */
+    Map<String, String> specialInputDescriptionsRegex = Collections.singletonMap("_arg\\d", "The _argN-th argument with which the instrumented method was called within which this action is getting executed.");
+
     /**
      * Generates a ConfigDocumentation from a YAML String describing an {@link InspectitConfig}.
      *
@@ -163,7 +185,27 @@ private List<ActionDocs> generateActionDocs(Map<String, GenericActionSettings> a
             Map<String, String> inputTypes = actionSettings.getInput();
 
             for (String inputName : inputTypes.keySet()) {
-                inputs.add(new ActionInputDocs(inputName, inputTypes.get(inputName), inputDescriptions.getOrDefault(inputName, "")));
+                String inputDescription = "";
+
+                if (inputName.startsWith("_")) {
+
+                    if (specialInputDescriptions.containsKey(inputName)) {
+                        inputDescription = specialInputDescriptions.get(inputName);
+
+                    } else {
+                        for (String inputNameRegex : specialInputDescriptionsRegex.keySet()) {
+                            Pattern pattern = Pattern.compile(inputNameRegex);
+                            Matcher matcher = pattern.matcher(inputName);
+                            if (matcher.matches()) {
+                                inputDescription = specialInputDescriptionsRegex.get(inputNameRegex);
+                            }
+                        }
+                    }
+                } else {
+                    inputDescription = inputDescriptions.getOrDefault(inputName, "");
+                }
+
+                inputs.add(new ActionInputDocs(inputName, inputTypes.get(inputName), inputDescription));
             }
             inputs.sort(Comparator.comparing(ActionInputDocs::getName));
 

components/inspectit-ocelot-configdocsgenerator/src/test/java/inspectit/ocelot/configdocsgenerator/ConfigDocsGeneratorTest.java

@@ -61,11 +61,21 @@ private static void createDocObjects() {
         // doc-key
         List<ActionInputDocs> inputs1 = new ArrayList<>();
 
-        ActionInputDocs actionInputDocsMock = Mockito.mock(ActionInputDocs.class);
-        when(actionInputDocsMock.getName()).thenReturn("value");
-        when(actionInputDocsMock.getType()).thenReturn("Object");
-        when(actionInputDocsMock.getDescription()).thenReturn("Object to be printed");
-        inputs1.add(actionInputDocsMock);
+        ActionInputDocs actionInputDocsMock1 = Mockito.mock(ActionInputDocs.class);
+        when(actionInputDocsMock1.getName()).thenReturn("_arg1");
+        when(actionInputDocsMock1.getType()).thenReturn("Object");
+        when(actionInputDocsMock1.getDescription()).thenReturn("The _argN-th argument with which the instrumented method was called within which this action is getting executed.");
+        inputs1.add(actionInputDocsMock1);
+        ActionInputDocs actionInputDocsMock2 = Mockito.mock(ActionInputDocs.class);
+        when(actionInputDocsMock2.getName()).thenReturn("_attachments");
+        when(actionInputDocsMock2.getType()).thenReturn("ObjectAttachments");
+        when(actionInputDocsMock2.getDescription()).thenReturn("Allows you to attach values to objects instead of to the control flow, as done via _context.");
+        inputs1.add(actionInputDocsMock2);
+        ActionInputDocs actionInputDocsMock3 = Mockito.mock(ActionInputDocs.class);
+        when(actionInputDocsMock3.getName()).thenReturn("value");
+        when(actionInputDocsMock3.getType()).thenReturn("Object");
+        when(actionInputDocsMock3.getDescription()).thenReturn("Object to be printed");
+        inputs1.add(actionInputDocsMock3);
 
         actionWithDocInYaml = Mockito.mock(ActionDocs.class);
         when(actionWithDocInYaml.getName()).thenReturn("a_debug_println");
@@ -78,17 +88,17 @@ private static void createDocObjects() {
         // Create a sample ActionDoc object where there was no documentation values in the YAML
         List<ActionInputDocs> inputs2 = new ArrayList<>();
 
-        ActionInputDocs actionInputDocsMock2 = Mockito.mock(ActionInputDocs.class);
-        when(actionInputDocsMock2.getName()).thenReturn("a");
-        when(actionInputDocsMock2.getType()).thenReturn("Object");
-        when(actionInputDocsMock2.getDescription()).thenReturn("");
-        inputs2.add(actionInputDocsMock2);
+        ActionInputDocs actionInputDocsMock4 = Mockito.mock(ActionInputDocs.class);
+        when(actionInputDocsMock4.getName()).thenReturn("a");
+        when(actionInputDocsMock4.getType()).thenReturn("Object");
+        when(actionInputDocsMock4.getDescription()).thenReturn("");
+        inputs2.add(actionInputDocsMock4);
 
-        ActionInputDocs actionInputDocsMock3 = Mockito.mock(ActionInputDocs.class);
-        when(actionInputDocsMock3.getName()).thenReturn("b");
-        when(actionInputDocsMock3.getType()).thenReturn("Object");
-        when(actionInputDocsMock3.getDescription()).thenReturn("");
-        inputs2.add(actionInputDocsMock3);
+        ActionInputDocs actionInputDocsMock5 = Mockito.mock(ActionInputDocs.class);
+        when(actionInputDocsMock5.getName()).thenReturn("b");
+        when(actionInputDocsMock5.getType()).thenReturn("Object");
+        when(actionInputDocsMock5.getDescription()).thenReturn("");
+        inputs2.add(actionInputDocsMock5);
 
         actionWithoutDocInYaml = Mockito.mock(ActionDocs.class);
         when(actionWithoutDocInYaml.getName()).thenReturn("a_debug_println_2");
@@ -345,4 +355,4 @@ void loadAll() throws IOException {
         }
     }
 
-}
+}

components/inspectit-ocelot-configdocsgenerator/src/test/resources/ConfigDocGeneratorTest/actionWithDocInYaml.yml

@@ -11,5 +11,7 @@ inspectit:
           since: '1.0'
         input:
           value: Object
+          _arg1: Object
+          _attachments: ObjectAttachments
         is-void: true
-        value: System.out.println(value);
+        value: System.out.println(value);

components/inspectit-ocelot-configdocsgenerator/src/test/resources/ConfigDocGeneratorTest/all.yml

@@ -21,6 +21,8 @@ inspectit:
           since: '1.0'
         input:
           value: Object
+          _arg1: Object
+          _attachments: ObjectAttachments
         is-void: true
         value: System.out.println(value);
 
@@ -38,7 +40,7 @@ inspectit:
           - name: executeUpdate
         advanced:
           instrument-only-inherited-methods: true
-      
+
     rules:
       r_tracing_global_attributes:
         exit:
@@ -92,4 +94,4 @@ inspectit:
         enabled: ${inspectit.metrics.disk.enabled.free}
         type: LONG
         unit: bytes
-        description: free disk space
+        description: free disk space

components/inspectit-ocelot-configdocsgenerator/src/test/resources/ConfigDocGeneratorTest/multipleActions.yml

@@ -21,5 +21,7 @@ inspectit:
           since: '1.0'
         input:
           value: Object
+          _arg1: Object
+          _attachments: ObjectAttachments
         is-void: true
-        value: System.out.println(value);
+        value: System.out.println(value);