indy advice docs & migration procedure

docs/contributing/writing-instrumentation-module.md

@@ -436,6 +436,40 @@ module classloader.
 
 This allows for example to access package-private methods that would not be accessible otherwise.
 
+### advice method signatures
+
+With inlined advices, the advice method signature does not have any limitations. It enables to refer
+to types in the OpenTelemetry API, SDK or instrumentation helper classes directly because those
+are injected in the target classloader or the bootstrap classloader for visibility.
+
+With indy advices however, the advice method signature can't introduce types that are not already
+visible from the instrumented method.
+In practice, two sets of types can be used in the advice method signature:
+- types from the JDK in the bootstrap classloader like `Object`
+- types already visible from the instrumented code
+
+For example, when trying to instrument a method that has `HttpServletRequest` as argument:
+- the `HttpServletRequest` type can be used as it's part of the instrumented code
+- the `HttpServletRequestScope` is part of instrumentation and has to be of type `Object` from enter return value and exit argument.
+
+```java
+@Advice.OnMethodEnter(suppress = Throwable.class, inlined = false)
+public static Object onEnter(@Advice.Argument(1) HttpServletRequest request) {
+  // custom type from the instrumentation module, has to be returned as Object
+  return new HttpServletRequestScope(request);
+}
+
+@Advice.OnMethodExit(suppress = Throwable.class, onThrowable = Throwable.class, inlined = false)
+public static void onExit(@Advice.Argument(1) Object request,
+                          @Advice.Enter Object enterScope) {
+  // enter scope provided as Object so we have to check type and cast
+  if (!(enterScope instanceof HttpServletRequestScope)) {
+    return;
+  }
+  HttpServletRequestScope requestScope = (HttpServletRequestScope)enterScope;
+}
+```
+
 ### advice local variables
 
 With inlined advices, declaring an advice method argument with `@Advice.Local` allows defining