Polish documentation for pkl-binary (#1250)

docs/modules/ROOT/partials/component-attributes.adoc

@@ -75,6 +75,7 @@ endif::[]
 :uri-stdlib-xmlModule: {uri-pkl-stdlib-docs}/xml
 :uri-stdlib-protobufModule: {uri-pkl-stdlib-docs}/protobuf
 :uri-stdlib-evaluatorSettingsModule: {uri-pkl-stdlib-docs}/EvaluatorSettings
+:uri-stdlib-pklbinaryModule: {uri-pkl-stdlib-docs}/pklbinary
 :uri-stdlib-evaluatorSettingsHttpClass: {uri-stdlib-evaluatorSettingsModule}/Http
 :uri-stdlib-Boolean: {uri-stdlib-baseModule}/Boolean
 :uri-stdlib-xor: {uri-stdlib-baseModule}/Boolean#xor()

docs/modules/bindings-specification/pages/binary-encoding.adoc

@@ -1,9 +1,15 @@
-= Pkl Binary Encoding
+= `pkl-binary` Encoding
 include::ROOT:partial$component-attributes.adoc[]
 include::partial$component-attributes.adoc[]
 
-Pkl values can be encoded into a binary format.
+:uri-pkl-core-Evaluator: {uri-pkl-core-main-sources}/Evaluator.java
-This format is used for Pkl's non-JVM language bindings, for example, for its Go and Swift bindings.
+
+Pkl values can be encoded into a binary format called "pkl-binary".
+This format is a lossless serialization of the underlying Pkl values.
+
+Pkl code can be rendered into this format using the {uri-stdlib-pklbinaryModule}[pkl:pklbinary] standard library module.
+
+Alternatively, many language bindings also provide methods to evaluate into `pkl-binary`, such as the `evaluateExpressionPklBinary` method in link:{uri-pkl-core-Evaluator}[org.pkl.core.Evaluator].
 
 The binary format is uses link:{uri-messagepack}[MessagePack] encoding.
 

stdlib/pklbinary.pkl

@@ -14,15 +14,30 @@
 // limitations under the License.
 //===----------------------------------------------------------------------===//
 
-/// APIs for handling Pkl's [binary encoding format](https://pkl-lang.org/main/current/bindings-specification/binary-encoding.html).
+/// APIs for working with `pkl-binary` encoding.
+///
+/// `pkl-binary` is a binary encoding of Pkl data.
+/// It can be used to encode all values, with the exception of [Function] types (lambda
+/// expressions).
+///
+/// `pkl-binary` encoding is useful for separating evaluation and data consumption into two
+/// separate steps.
+/// For example, applications can produce `pkl-binary` at build time, and deserialize this into
+/// code-generated structs at application runtime.
+///
+/// The `pkl-binary` format uses MessagePack encoding.
+/// Its specification is available at
+/// <https://pkl-lang.org/main/current/bindings-specification/binary-encoding.html>.
 @ModuleInfo { minPklVersion = "0.30.0" }
 module pkl.pklbinary
 
-/// Render values as the [`pkl-binary` encoding format](https://pkl-lang.org/main/current/bindings-specification/binary-encoding.html).
+/// Render values as `pkl-binary`.
 class Renderer extends BytesRenderer {
-  /// Render a Pkl value as `pkl-binary`.
+  /// Renders [value] as `pkl-binary`.
   external function renderValue(value: Any): Bytes
 
-  /// Render a Pkl document as `pkl-binary`.
+  /// Renders [value] as `pkl-binary`.
+  ///
+  /// Every `pkl-binary` value is also a valid document.
   external function renderDocument(value: Any): Bytes
 }