[CLC-215]: Serializer Generator Documentation (hazelcast#406)

Author: Kutluhan Metin

docs/modules/ROOT/nav.adoc

@@ -33,6 +33,7 @@
 ** xref:clc-version.adoc[]
 ** xref:clc-viridian.adoc[]
 ** xref:clc-project.adoc[]
+** xref:clc-serializer-generator.adoc[]
 * xref:configuration-format.adoc[]
 * xref:environment-variables.adoc[]
 * xref:keyboard-shortcuts.adoc[]

docs/modules/ROOT/pages/clc-serializer-generator.adoc

@@ -0,0 +1,139 @@
+= clc serializer generator (Beta)
+
+Serializer commands are a group of serializer generator operations.
+
+Check out the documentation for https://docs.hazelcast.com/hazelcast/latest/serialization/compact-serialization[Compact Serialization] for more information.
+
+Usage:
+
+[source,bash]
+----
+clc serializer [command] [flags]
+----
+
+== Commands
+
+* <<clc-serializer-generate, clc serializer generate>>
+
+== clc serializer generate
+
+Generates compact serialization code from the given schema for the target language. See https://docs.hazelcast.com/hazelcast/latest/serialization/compact-serialization#implementing-compactserializer[Compact Serialization] documentation for more information.
+
+Usage:
+
+[source, bash]
+----
+clc serializer generate [schema] [flags]
+----
+
+Parameters:
+
+[cols="1m,1a,2a,1a"]
+|===
+|Parameter|Required|Description|Default
+
+|`output-dir`, `-o`
+|Optional
+|Output directory for the serialization files.
+|Current working directory.
+
+|`language`, `-l`
+|Required
+|Programming language that the serializer created for.
+|
+|===
+
+Example:
+
+[source,bash]
+----
+clc serializer generate my-schema.yaml --language java --output-dir my-dir
+----
+
+=== Schema Creation
+
+A schema allows you to:
+
+* describe the contents of a compact class using supported field types
+* import other schema
+* specify a namespaces for schema files and reference other namespaces
+* define cyclic references between classes
+* reference classes that are not present in the given schemas
+
+A schema is written in YAML. Schema format is given below:
+
+[source,yaml]
+----
+namespace: <namespace of the class>
+# note that other schema files can be imported with relative path to this yaml file
+imports:
+ - someOtherSchema.yaml
+# All objects in this file will share the same namespace.
+classes:
+ - name: <name of the class>
+   fields:
+     - name: <field name>
+       type: <field type>
+       external: bool # to mark external types (external to this yaml file)
+----
+
+==== namespace
+
+Used for logical grouping of classes. Typically, for every namespace, you will have a schema file. Namespace is optional. If not provided, the classes will be generated at global namespace (no namespace). The user should provide the language specific best practice when using the namespace. The tool will use the namespace while generating code if provided.
+
+==== imports
+
+Used to import other schema files. The type definitions in the imported yaml schemas can be used within this yaml file. Cyclic imports will be checked and handled properly. For this version of the tool, an import can only be a single file name and the tool will assume all yaml files imported will be in the same directory as the importing schema file.
+
+==== classes
+
+Used to define classes in the schema.
+
+* name: Name of the class
+* fields: Field specification of the class
+** name: Name of the field
+** type: Type of the field. Normally you should refer to another class as namespace.classname. You can use a class without namespace when the class is defined in the same schema yaml file. type can be one of the following:
+*** `boolean`
+*** `boolean[]`
+*** `int8`
+*** `int8[]`
+*** `int16`
+*** `int16[]`
+*** `int32`
+*** `int32[]`
+*** `int64`
+*** `int64[]`
+*** `float32`
+*** `float32[]`
+*** `float64`
+*** `float64[]`
+*** `string`
+*** `string[]`
+*** `date`
+*** `date[]`
+*** `time`
+*** `time[]`
+*** `timestamp`
+*** `timestamp[]`
+*** `timestampWithTimezone`
+*** `timestampWithTimezone[]`
+*** `nullableBoolean`
+*** `nullableBoolean[]`
+*** `nullableInt8`
+*** `nullableInt8[]`
+*** `nullableInt16`
+*** `nullableInt16[]`
+*** `nullableInt32`
+*** `nullableInt32[]`
+*** `nullableInt64`
+*** `nullableInt64[]`
+*** `nullableFloat32`
+*** `nullableFloat32[]`
+*** `nullableFloat64`
+*** `nullableFloat64[]`
+*** `<OtherCompactClass[]>`
+** external:
+*** Used to mark if the type is external. If a field is external, the tool will not check if it is imported and available. External types are managed by the user and not generated by the tool.
+*** The serializer of an external field can be a custom serializer which is handwritten, the zero-config serializer for Java and .NET, or previously genereated using the tool. This flag will enable such mixed use cases.
+*** In generated code, external types are imported exactly what as the "type" of the field, hence for languages like Java the user should enter the full package name together with the class. E.g. type: `com.app1.dto.Address`.
+