docs

enso-org · Jul 5, 2022 · 0f9d31e · 0f9d31e
1 parent d7ac60a
commit 0f9d31e
Show file tree

Hide file tree

Showing 2 changed files with 16 additions and 2 deletions.
diff --git a/std-bits/base/src/main/java/org/enso/base/Encoding_Utils.java b/std-bits/base/src/main/java/org/enso/base/Encoding_Utils.java
@@ -163,6 +163,9 @@ private static ReportingStreamDecoder create_stream_decoder(InputStream stream,
 
   /**
    * A helper function which runs an action with a created stream decoder and closes it afterwards.
+   *
+   * <p>It returns the result returned from the executed action and any encoding problems that
+   * occurred when processing it.
    */
   public static <R> WithProblems<R, String> with_stream_decoder(
       InputStream stream, Charset charset, Function<ReportingStreamDecoder, R> action)
@@ -191,6 +194,9 @@ private static ReportingStreamEncoder create_stream_encoder(
 
   /**
    * A helper function which runs an action with a created stream encoder and closes it afterwards.
+   *
+   * <p>It returns the result returned from the executed action and any encoding problems that
+   * occurred when processing it.
    */
   public static <R> WithProblems<R, String> with_stream_encoder(
       OutputStream stream,

diff --git a/std-bits/base/src/main/java/org/enso/base/encoding/ReportingStreamEncoder.java b/std-bits/base/src/main/java/org/enso/base/encoding/ReportingStreamEncoder.java
@@ -8,14 +8,22 @@
 import java.io.Writer;
 import java.nio.ByteBuffer;
 import java.nio.CharBuffer;
-import java.nio.charset.Charset;
 import java.nio.charset.CharsetEncoder;
 import java.nio.charset.CoderResult;
 import java.util.ArrayList;
-import java.util.Arrays;
 import java.util.List;
 import java.util.stream.Collectors;
 
+/**
+ * A {@code Writer} which encodes any characters provided to itself using the provided {@code
+ * CharsetEncoder} and passes the encoded data to the provided {@code OutputStream}.
+ *
+ * <p>Functionally, it should be equivalent to {@code java.io.OutputStreamWriter}. The major
+ * difference is that this class allows more granular reporting of encoding issues - instead of just
+ * replacing malformed characters with a replacement or failing at the first error, it allows to
+ * both perform the replacements but also remember the positions at which the problems occurred and
+ * then return a bulk report of places where the issues have been encountered.
+ */
 public class ReportingStreamEncoder extends Writer {
 
   /**