Changed general redaction and some examples in docs

docs/wiki/file_manipulation.md

@@ -1,14 +1,14 @@
 # Handling files and doing operations
 
-Beyond simple read and write operations, this section allows you to interact directly with the file system. There are functions for creating and deleting files and directories, creating temporary files for short-term use, and managing file and directory permissions for added control, among other useful methods.
+Beyond simple file reading and writing operations, Shellfish allows you to interact directly with the file system. There are functions for creating and deleting files and directories, creating temporary files for short-term use and managing file and directory permissions for added control, among other useful methods.
 
 ## Creating files and directories
 
 In this section, you will see how to create new files and directories, as well as delete existing ones.
 
 ### `createFile`    
 
-Creates a new file in the specified path, failing if the parent directory does not exist. You can also specify some permissions if you wish. To see what the `exists` function does, see [the reference](#exists):
+Creates a new file in the specified path, failing if the parent directory does not exist. It optionally accepts file permissions. To see what the `exists` function does, see [the reference](#exists):  
 
 ```scala mdoc:invisible
 // This section adds every import to the code snippets
@@ -97,7 +97,8 @@ Files[IO].createDirectories(directories) >> Files[IO].createFile(path)
 
 ### `createTempFile`
 
-This function creates a temporary file that gets automatically deleted by the operating system. It optionally accepts multiple parameters such as a directory, a prefix (the name of the file), a suffix (the extension of the file) and permissions. It returns the path of the newly created file:
+This function creates a temporary file that gets automatically deleted. It optionally accepts multiple parameters such as a directory, a prefix (to the name of the file), a suffix (like the extension of the file) and permissions. It returns the path of the newly created file:  
+
 
 @:select(api-style)
 
@@ -343,9 +344,7 @@ Files[IO].deleteIfExists(path) >>=
 
 ### `deleteRecursively`
 
-With the previous functions, the directory had to be empty to be deleted. The difference with this method is that it recursively deletes all files or folders contained inside it, optionally following symbolic links if specified: 
-
-Recursively deletes all files or folders, following symbolic links if specified. 
+With the previous functions, the directory had to be empty to be deleted. The difference with this method is that it recursively deletes all files or folders contained inside it, optionally following symbolic links if specified.
 
 Note that, unlike the previous functions, this one will not fail if the directories are empty or do not exist:
 
@@ -394,7 +393,8 @@ Working directly with files is a common need in many scripting scenarios. This l
 
 ### `copy`
 
-Copies a file from a source path to a target path. The method will fail if the destination path already exists; to avoid this behaviour, you can pass flags to e.g., replace the contents in the destination:
+Copies a file from a source path to a target path. The method will fail if the destination path already exists; to avoid this behaviour, you can, for example, pass flags to replace the contents at destination:  
+
 
 @:select(api-style)
 

docs/wiki/file_reading_writing.md

@@ -1,6 +1,6 @@
 # Reading, writing, and appending 
 
-This library comes with three different functions for reading and writing operations, `read`, `write` and `append`, each with four different variants: Standalone, `Bytes`, `Lines` and `As`, with these variants you will be able to work with the file and/or its contents as a UTF-8 string or with a custom `java.nio.charset.Charset`, as bytes, line by line, and with a custom codec respectively. 
+Shellfish comes with three different functions for reading and writing operations, `read`, `write` and `append`, each with four different variants: Standalone, `Bytes`, `Lines` and `As`, with these variants you will be able to work with the file and/or its contents as a UTF-8 string or with a custom `java.nio.charset.Charset`, as bytes, line by line, and with a custom codec respectively. 
 
 ```scala mdoc:invisible
 // This section adds every import to the code snippets
@@ -64,7 +64,7 @@ Files[IO].readUtf8(path).evalMap(IO.println).compile.drain
 
 @:@
 
-If UTF-8 is not your favorite flavour, you can also use a custom `java.nio.charset.Charset` to decode your file:
+If you need to handle non UTF-8 files, you can also use a custom `java.nio.charset.Charset`:  
 
 @:select(api-style)
 
@@ -100,7 +100,7 @@ Files[IO].readAll(path)
 
 ### `readBytes`
 
-Reads the file as a `ByteVector`, useful when working with binary data:
+Reads the file as a [`ByteVector`](https://scodec.org/guide/scodec-bits.html#ByteVector), useful when working with binary data:
 
 @:select(api-style)
 
@@ -126,10 +126,13 @@ Files[IO].readAll(path).compile.to(ByteVector).map(_.rotateLeft(2))
 
 @:@
 
+If you are not used to working with bytes and bits in general, `rotateLeft(N)` will shift bits N number of places to the left! For example, if we rotate to the left 11100101 three times, we will get 00101111.
+
+
 
 ### `readLines`
 
-Similar to `read` as it reads the file as a UTF-8 string, but stores each line of the file on a `List`:
+Similar to `read` as it reads the file as a UTF-8 string, but stores each line of the file in a `List`:  
 
 @:select(api-style)
 
@@ -138,7 +141,7 @@ Similar to `read` as it reads the file as a UTF-8 string, but stores each line o
 ```scala mdoc:compile-only
 for
   lines <- path.readLines
-  _     <- IO(lines.foreach(println))
+  _     <- lines.traverse_(IO.println)  
 yield ()
 ```
 
@@ -162,7 +165,7 @@ Files[IO].readUtf8Lines(path).evalMap(IO.println).compile.drain
 
 ### `readAs`
 
-This method reads the contents of the file given a `Codec[A]` in scope, useful when you want to convert a file into a custom type `A`:
+This method reads the contents of the file given a `Codec[A]`. Useful when you want to convert a binary file into a custom type `A`:  
 
 @:select(api-style)
 
@@ -282,7 +285,7 @@ The default charset can also be changed for encoding when writing strings:
 ```scala 3 mdoc:compile-only
 import java.nio.charset.StandardCharsets
 
-val message = "Imagine writing Java 😭"
+val message = "Java? No thanks, I'm allergic to coffee λ"
 
 path.write(message, StandardCharsets.US_ASCII)
 ```
@@ -292,7 +295,7 @@ path.write(message, StandardCharsets.US_ASCII)
 ```scala 3 mdoc:compile-only
 import java.nio.charset.StandardCharsets
 
-val message = "Imagine writing Java 😭"
+val message = "Java? No thanks, I'm allergic to coffee λ"
 
 FilesOs.write(path, message, StandardCharsets.US_ASCII)
 ```
@@ -303,7 +306,7 @@ FilesOs.write(path, message, StandardCharsets.US_ASCII)
 import fs2.text.encode
 import java.nio.charset.StandardCharsets
 
-val message = "Imagine writing Java 😭"
+val message = "Java? No thanks, I'm allergic to coffee λ"
 
 Stream.emit(message)
   .through(encode(StandardCharsets.US_ASCII))
@@ -324,7 +327,7 @@ With this method you can write bytes directly to a binary file. The contents of
 
 ```scala mdoc:compile-only
 import scodec.bits.*
-val niceBytes = hex"BadBabe"
+val niceBytes = hex"DeadC0de"
 
 path.writeBytes(niceBytes)
 ```
@@ -333,7 +336,7 @@ path.writeBytes(niceBytes)
 
 ```scala mdoc:compile-only
 import scodec.bits.*
-val niceBytes = hex"BadBabe"
+val niceBytes = hex"DeadC0de"
 
 FilesOs.writeBytes(path, niceBytes)
 ```
@@ -344,7 +347,7 @@ FilesOs.writeBytes(path, niceBytes)
 
 
 import scodec.bits.*
-val niceBytes = hex"BadBabe"
+val niceBytes = hex"DeadC0de"
 
 Stream.chunk(fs2.Chunk.byteVector(niceBytes))
   .covary[IO]