Merge pull request #6533 from lukewilliamboswell/encode-docs

Docs for `Encode` builtin

crates/compiler/builtins/roc/Encode.roc

@@ -73,14 +73,46 @@ EncoderFormatting implements
     tuple : List (Encoder fmt) -> Encoder fmt where fmt implements EncoderFormatting
     tag : Str, List (Encoder fmt) -> Encoder fmt where fmt implements EncoderFormatting
 
+## Creates a custom encoder from a given function.
+##
+## ```
+## expect
+##     # Appends the byte 42
+##     customEncoder = Encode.custom (\bytes, _fmt -> List.append bytes 42)
+##
+##     actual = Encode.appendWith [] customEncoder Core.json
+##     expected = [42] # Expected result is a list with a single byte, 42
+##
+##     actual == expected
+## ```
 custom : (List U8, fmt -> List U8) -> Encoder fmt where fmt implements EncoderFormatting
 custom = \encoder -> @Encoder encoder
 
 appendWith : List U8, Encoder fmt, fmt -> List U8 where fmt implements EncoderFormatting
 appendWith = \lst, @Encoder doEncoding, fmt -> doEncoding lst fmt
 
+## Appends the encoded representation of a value to an existing list of bytes.
+##
+## ```
+## expect
+##     actual = Encode.append [] { foo: 43 } Core.json
+##     expected = Str.toUtf8 """{"foo":43}"""
+##
+##     actual == expected
+## ```
 append : List U8, val, fmt -> List U8 where val implements Encoding, fmt implements EncoderFormatting
 append = \lst, val, fmt -> appendWith lst (toEncoder val) fmt
 
+## Encodes a value to a list of bytes (`List U8`) according to the specified format.
+##
+## ```
+## expect
+##     fooRec = { foo: 42 }
+##
+##     actual = Encode.toBytes fooRec Core.json
+##     expected = Str.toUtf8 """{"foo":42}"""
+##
+##     actual == expected
+## ```
 toBytes : val, fmt -> List U8 where val implements Encoding, fmt implements EncoderFormatting
 toBytes = \val, fmt -> appendWith [] (toEncoder val) fmt