Document how to manipulate attachments via hints (#5070)

* Document how to manipulate attachments via hints

* Apply suggestions from code review

Co-authored-by: Isabel <[email protected]>

* Update src/includes/enriching-events/add-attachment/java.mdx

Co-authored-by: Isabel <[email protected]>

* Apply suggestions from code review

Co-authored-by: Isabel <[email protected]>

Author: adinauer

src/includes/enriching-events/add-attachment/java.mdx

@@ -0,0 +1,110 @@
+To add an attachment, you can either add it to the scope, pass it to any of the `capture` methods, or manipulate the list of attachments in an `EventProcessor` or `beforeSend`.
+
+### Passing Attachments to Capture
+
+You may pass attachments to any of the `capture` methods, for example, when capturing an exception:
+
+```java
+import io.sentry.Attachment;
+import io.sentry.Hint;
+import io.sentry.Sentry;
+
+Sentry.captureException(new IllegalStateException(), Hint.withAttachment("/path/to/file.txt"))
+```
+
+```kotlin
+import io.sentry.Attachment;
+import io.sentry.Hint;
+import io.sentry.Sentry;
+
+Sentry.captureException(IllegalStateException(), Hint.withAttachment("/path/to/file.txt"))
+```
+
+### Adding Attachments in `EventProcessor`
+
+You may also manipulate attachments in `EventProcessor`:
+
+```java
+import io.sentry.Attachment;
+import io.sentry.EventProcessor;
+import io.sentry.Hint;
+import io.sentry.Sentry;
+import io.sentry.SentryEvent;
+
+class AttachmentManipulationEventProcessor implements EventProcessor {
+  @Override
+  public SentryEvent process(SentryEvent event, Hint hint) {
+    hint.addAttachment(new Attachment("/path/to/file.txt"))
+    return event;
+  }
+}
+
+// Register the AttachmentManipulationEventProcessor using SentryOptions#addEventProcessor or Scope#addEventProcessor
+
+// Send an event to Sentry. During construction of the event
+// the attachment will be added by the event processor.
+Sentry.captureMessage("Hello, world!");
+```
+
+```kotlin
+import io.sentry.Attachment;
+import io.sentry.EventProcessor;
+import io.sentry.Hint;
+import io.sentry.Sentry
+import io.sentry.SentryEvent;
+import io.sentry.protocol.Message
+
+class AttachmentManipulationEventProcessor: EventProcessor {
+  override fun process(event: SentryEvent, hint: Hint): SentryEvent? {
+    hint.addAttachment(Attachment("/path/to/file.txt"))
+    return event
+  }
+}
+
+// Register the AttachmentManipulationEventProcessor using SentryOptions#addEventProcessor or Scope#addEventProcessor
+
+// Send an event to Sentry. During construction of the event
+// the attachment will be added by the event processor.
+Sentry.captureMessage("Hello, world!")
+```
+
+<Note>
+
+Instead of adding attachments, you can also remove them, by setting a different (or empty) list of attachments using `Hint#setAttachments()`.
+
+</Note>
+
+### Adding Attachments in `beforeSend`
+
+Another way of adding attachments is using `beforeSend`:
+
+```java
+import io.sentry.Attachment;
+import io.sentry.Hint;
+import io.sentry.Sentry;
+
+options.setBeforeSend((event, hint) -> {
+  hint.addAttachment(new Attachment("/path/to/file.txt"))
+  return event;
+});
+```
+
+```kotlin
+import io.sentry.Attachment;
+import io.sentry.Hint;
+import io.sentry.Sentry;
+import io.sentry.SentryOptions.BeforeSendCallback
+
+options.beforeSend = BeforeSendCallback { event, hint ->
+  hint.addAttachment(Attachment("/path/to/file.txt"))
+  event
+}
+```
+
+<Note>
+
+Instead of adding attachments, you can also remove them, by setting a different (or empty) list of attachments using `Hint#setAttachments()`.
+
+</Note>
+
+### Adding Attachments to the Scope

src/platforms/common/enriching-events/attachments/index.mdx

@@ -84,7 +84,7 @@ In addition, you can set these parameters:
 
 ## Uploading Attachments
 
-<PlatformSection supported={["native", "javascript"]}>
+<PlatformSection supported={["native", "javascript", "java"]}>
 
 <PlatformSection supported={["javascript", "node"]}>