Document all default instrumentations (#1419)

Co-authored-by: Henning Schulz <henning.schulz@novatec-gmbh.de>
Co-authored-by: Marius Oehler <marius.oehler@novatec-gmbh.de>

Author: 3 people

inspectit-ocelot-config/src/main/resources/rocks/inspectit/ocelot/config/default/instrumentation/actions/_shared/assignment.yml

@@ -1,18 +1,36 @@
 inspectit:
   instrumentation:
     actions:
-      
+
       'a_assign_value':
+        docs:
+          since: '1.2.1'
+          description: 'Returns the input value.'
+          inputs:
+            'value': 'The value to return.'
+          return-value: 'The input value.'
         input:
           'value': 'Object'
         value: 'value'
 
       'a_assign_null':
+        docs:
+          since: '1.2.1'
+          description: 'Returns null.'
+          return-value: 'null'
         value-body: 'return null;'
-        
+
       'a_assign_true':
+        docs:
+          since: '1.2.1'
+          description: 'Returns true.'
+          return-value: 'true'
         value: 'Boolean.TRUE'
-        
+
       'a_assign_false':
+        docs:
+          since: '1.2.1'
+          description: 'Returns false.'
+          return-value: 'false'
         value: 'Boolean.FALSE'
-        
+

inspectit-ocelot-config/src/main/resources/rocks/inspectit/ocelot/config/default/instrumentation/actions/_shared/attachment.yml

@@ -4,7 +4,12 @@ inspectit:
 
       'a_attachment_get':
         docs:
-          description: 'Reads a given attachment from a target object.'
+          since: '1.2.1'
+          description: 'Reads the attachment with a given key from a target Object.'
+          inputs:
+            'target': 'The target Object.'
+            'key': 'The key of the attachment.'
+          return-value: 'The attachment Object.'
         input:
           _attachments: 'ObjectAttachments'
           'target': 'Object'
@@ -13,7 +18,13 @@ inspectit:
 
       'a_attachment_put':
         docs:
-          description: 'Replaces a given attachment of a target object with a new one, returns the previous value.'
+          since: '1.2.1'
+          description: 'Replaces the attachment with a given key of a target object with a new one. Returns the previous value.'
+          inputs:
+            'target': 'The target object.'
+            'key': 'The key of the attachment.'
+            'value': 'The new value for the attachment.'
+          return-value: 'The previous value of the replaced attachment.'
         input:
           _attachments: ObjectAttachments
           'target': Object
@@ -23,7 +34,12 @@ inspectit:
 
       'a_attachment_remove':
         docs:
-          description: 'Removes a given attachment from a target object, returning the previously attached value.'
+          since: '1.2.1'
+          description: 'Removes a given attachment from a target object. Returns the previous value.'
+          inputs:
+            'target': 'The target object.'
+            'key': 'The key of the attachment.'
+          return-value: 'The previous value of the removed attachment.'
         input:
           _attachments: ObjectAttachments
           'target': Object

inspectit-ocelot-config/src/main/resources/rocks/inspectit/ocelot/config/default/instrumentation/actions/_shared/debug.yml

@@ -4,7 +4,10 @@ inspectit:
 
       'a_debug_println':
         docs:
-          description: 'Prints a given Object to stdout.'
+          since: '1.2.1'
+          description: 'Prints a given object to stdout.'
+          inputs:
+            'value': 'The object to print.'
         input:
           'value': 'Object'
         is-void: true
@@ -13,7 +16,11 @@ inspectit:
 
       'a_debug_println_2':
         docs:
-          description: 'Prints two given Objects to stdout.'
+          since: '1.2.1'
+          description: 'Prints two given objects to stdout in the format "A + B".'
+          inputs:
+            'a': 'The first object to print.'
+            'b': 'The second object to print.'
         input:
           'a': 'Object'
           'b': 'Object'

inspectit-ocelot-config/src/main/resources/rocks/inspectit/ocelot/config/default/instrumentation/actions/_shared/entrypoint.yml

@@ -1,18 +1,18 @@
 inspectit:
   instrumentation:
     actions:
-    
-      #
+
       'a_entrypoint_check':
         docs:
+          since: '1.2.1'
           description: |-
             Utility function to detect entry methods.
-            This functions checks if a given "marker" is present on the context.
-            The marker should be configured for down-propagation.
-            If the marker is not present, it is added to the context and "true" is returned.
-            If it is present, false is returned.
-            E.g. if methodA calls methodB and they both invoke "a_entrypoint_check" with the same marker,
-            "true" will only be returned for methodA.
+            This function checks if a given marker is present on the context. The marker should be configured for down-propagation.
+            If the marker is not present, it is added to the context and 'true' is returned. If it is present, 'false' is returned.
+            E.g. if methodA calls methodB and they both invoke "a_entrypoint_check" with the same marker, 'true' will only be returned for methodA.
+          inputs:
+            'marker': 'The marker.'
+          return-value: 'True if the marker is not present, false if it is.'
         input:
           _context: 'InspectitContext'
           'marker': 'String'

inspectit-ocelot-config/src/main/resources/rocks/inspectit/ocelot/config/default/instrumentation/actions/_shared/logic.yml

@@ -4,42 +4,61 @@ inspectit:
 
       'a_logic_isNull':
         docs:
-          description: 'Returns true, if the given Object is null, false otherwise.'
+          since: '1.2.1'
+          description: 'Returns true, if the given object is null, false otherwise.'
+          inputs:
+            'value': 'The object to compare.'
+          return-value: 'True, if the given object is null, false otherwise.'
         input:
           'value': 'Object'
         value: 'Boolean.valueOf(value == null)'
 
       'a_logic_isNotNull':
         docs:
-          description: 'Returns true, if the given Object is not null, false otherwise.'
+          since: '1.2.1'
+          description: 'Returns true, if the given object is not null, false otherwise.'
+          inputs:
+            'value': 'The object to compare.'
+          return-value: 'True, if the given object is not null, false otherwise.'
         input:
           'value': 'Object'
         value: 'Boolean.valueOf(value != null)'
 
       'a_logic_and':
         docs:
+          since: '1.2.1'
           description: 'Returns true, if both provided arguments are not null and true.'
+          inputs:
+            'a': 'First Boolean.'
+            'b': 'Second Boolean.'
+          return-value: 'True, if both provided arguments are not null and true.'
         input:
           'a': 'Boolean'
           'b': 'Boolean'
         value: 'Boolean.valueOf((a != null && a.booleanValue()) && (b != null && b.booleanValue()))'
 
       'a_logic_or':
         docs:
+          since: '1.2.1'
           description: 'Returns true, if one of the provided arguments is not null and true.'
+          inputs:
+            'a': 'First Boolean.'
+            'b': 'Second Boolean.'
+          return-value: 'True, if one of the provided arguments is not null and true.'
         input:
           'a': 'Boolean'
           'b': 'Boolean'
         value: 'Boolean.valueOf((a != null && a.booleanValue()) || (b != null && b.booleanValue()))'
 
-      #
       'a_logic_isTrueOrNotNull':
         docs:
+          since: '1.14.0'
           description: |-
             Returns whether the input value is set or represents a true value. 
             The action will return true in case a true-Boolean or any other object is passed into the input parameter.
-          
-            Since: 1.14.0'
+          inputs:
+            'value': 'The input value.'
+          return-value: 'True, if the input value is set or represents a true value.'
         input:
           'value': 'Object'
         value-body: |
@@ -49,4 +68,4 @@ inspectit:
           if (value instanceof String) {
             return Boolean.valueOf(Boolean.parseBoolean((String) value));
           }
-          return Boolean.valueOf(value != null);
+          return Boolean.valueOf(value != null);

inspectit-ocelot-config/src/main/resources/rocks/inspectit/ocelot/config/default/instrumentation/actions/_shared/method.yml

@@ -1,14 +1,16 @@
 inspectit:
-  instrumentation:  
+  instrumentation:
     actions:
 
       'a_method_getFQN':
         docs:
-          description: 'Returns the full qualified name of the current method, e.g. "my.package.MyClass.myMethod".'
+          since: '1.2.1'
+          description: 'Returns the fully qualified name of the current method, e.g. "my.package.MyClass.myMethod".'
+          return-value: 'The fully qualified name of the current method as a String.'
         input:
           _class: 'Class'
           _methodName: 'String'
-          '_parameterTypes': 'Class[]'
+          _parameterTypes: 'Class[]'
         value-body: |
           StringBuilder sb = new StringBuilder();
           sb.append(_class.getName()).append('.');
@@ -24,10 +26,12 @@ inspectit:
 
       'a_method_getNameWithParameters':
         docs:
+          since: '1.2.1'
           description: 'Returns the name of the method with the simple parameter list, e.g. "myMethod(int, String, MyClass)".'
+          return-value: 'The name of the method with the simple parameter list as a String.'
         input:
           _methodName: 'String'
-          '_parameterTypes': 'Class[]'
+          _parameterTypes: 'Class[]'
         value-body: |
           StringBuilder sb = new StringBuilder();
           sb.append(_methodName).append('(');
@@ -42,7 +46,9 @@ inspectit:
 
       'a_method_getClassFQN':
         docs:
-          description: 'Returns the full qualified name of the class declaring the current method, e.g. "my.package.MyClass".'
+          since: '1.2.1'
+          description: 'Returns the fully qualified name of the class declaring the current method, e.g. "my.package.MyClass".'
+          return-value: 'The fully qualified name of the class declaring the current method.'
         input:
           _class: 'Class'
         value: '_class.getName()'