diff --git a/library/opusencoder/src/main/cpp/codec/CodecOggOpus.cpp b/library/opusencoder/src/main/cpp/codec/CodecOggOpus.cpp
index 3b28780ef0..d167c69cbf 100644
--- a/library/opusencoder/src/main/cpp/codec/CodecOggOpus.cpp
+++ b/library/opusencoder/src/main/cpp/codec/CodecOggOpus.cpp
@@ -20,9 +20,13 @@
 int ret;
 
 int CodecOggOpus::encoderInit(char* filePath, int sampleRate) {
+    // Create default, empty comment header
     comments = ope_comments_create();
-    int numChannels = 1; // Mono audio
-    int family = 0; // Channel Mapping Family 0, used for mono/stereo streams
+    // Mono audio
+    int numChannels = 1;
+    // Channel Mapping Family 0, used for mono/stereo streams
+    int family = 0;
+    // Create encoder to encode PCM chunks and write the result to a file with the OggOpus framing
     encoder = ope_encoder_create_file(filePath, comments, sampleRate, numChannels, family, &ret);
     if (ret != OPE_OK) {
         LOGE(TAG, "Creation of OggOpusEnc failed.");
@@ -41,12 +45,16 @@ int CodecOggOpus::setBitrate(int bitrate) {
 }
 
 int CodecOggOpus::writeFrame(short* frame, int samplesPerChannel) {
+    // Encode the raw PCM-16 buffer to Opus and write it to the ogg file
     return ope_encoder_write(encoder, frame, samplesPerChannel);
 }
 
 void CodecOggOpus::encoderRelease() {
+    // Finish any pending encode/write operations
     ope_encoder_drain(encoder);
+    // De-init the encoder instance
     ope_encoder_destroy(encoder);
+    // De-init the comment header struct
     ope_comments_destroy(comments);
 }
 
diff --git a/library/opusencoder/src/main/cpp/codec/CodecOggOpus.h b/library/opusencoder/src/main/cpp/codec/CodecOggOpus.h
index 5c94a0d874..f1035434c5 100644
--- a/library/opusencoder/src/main/cpp/codec/CodecOggOpus.h
+++ b/library/opusencoder/src/main/cpp/codec/CodecOggOpus.h
@@ -18,7 +18,16 @@
 #define ELEMENT_ANDROID_CODECOGGOPUS_H
 
 #include <opusenc.h>
-
+/**
+ * This class is a wrapper around libopusenc, used to encode and write Opus frames into an Ogg file.
+ *
+ * The usual flow would be:
+ *
+ * 1. Use encoderInit to initialize the internal encoder with the sample rate and the path to write the encoded frames to.
+ * 2. (Optional) set the bitrate to use.
+ * 3. While recording, read PCM-16 chunks from the recorder, feed them to the encoder using writeFrame.
+ * 4. When finished, call encoderRelease to free some resources.
+ */
 class CodecOggOpus {
 
 private:
diff --git a/library/opusencoder/src/main/java/im/vector/opusencoder/OggOpusEncoder.kt b/library/opusencoder/src/main/java/im/vector/opusencoder/OggOpusEncoder.kt
index 8f035e1660..8af11f8516 100644
--- a/library/opusencoder/src/main/java/im/vector/opusencoder/OggOpusEncoder.kt
+++ b/library/opusencoder/src/main/java/im/vector/opusencoder/OggOpusEncoder.kt
@@ -20,6 +20,9 @@ import android.util.Log
 import androidx.annotation.IntRange
 import im.vector.opusencoder.configuration.SampleRate
 
+/**
+ * JNI bridge to CodecOggOpus in the native opuscodec library.
+ */
 class OggOpusEncoder {
 
     companion object {