Annotate basic schema columns

Neos.ContentRepository.Core/Classes/Infrastructure/DbalSchemaFactory.php

@@ -5,6 +5,10 @@
 use Doctrine\DBAL\Schema\Schema;
 use Doctrine\DBAL\Schema\Table;
 use Doctrine\DBAL\Types\Types;
+use Neos\ContentRepository\Core\DimensionSpace\DimensionSpacePoint;
+use Neos\ContentRepository\Core\NodeType\NodeTypeName;
+use Neos\ContentRepository\Core\SharedModel\Node\NodeAggregateId;
+use Neos\ContentRepository\Core\SharedModel\Workspace\ContentStreamId;
 
 /**
  * Provide doctrine DBAL column schema definitions for common types in the content repository to
@@ -14,6 +18,10 @@
  */
 final class DbalSchemaFactory
 {
+    /**
+     * The NodeAggregateId is limited to 64 ascii characters and therefore we should do the same in the database.
+     * @see NodeAggregateId
+     */
     public static function addColumnForNodeAggregateId(Table $table, string $columnName, bool $notNull): Table
     {
         $table->addColumn($columnName, Types::STRING)
@@ -25,6 +33,16 @@ public static function addColumnForNodeAggregateId(Table $table, string $columnN
         return $table;
     }
 
+    /**
+     * The ContentStreamId is generally a UUID, therefore not a real "string" but at the moment a strified identifier,
+     * we can safely store it as binary string as the charset doesn't matter
+     * for the characters we use (they are all asscii).
+     *
+     * We should however reduce the allowed size to 36 like suggested
+     * here in the schema and as further improvement store the UUID in a more DB friendly format.
+     *
+     * @see ContentStreamId
+     */
     public static function addColumnForContentStreamId(Table $table, string $columnName, bool $notNull): Table
     {
         $table->addColumn($columnName, Types::STRING)
@@ -35,6 +53,14 @@ public static function addColumnForContentStreamId(Table $table, string $columnN
         return $table;
     }
 
+    /**
+     * An anchorpoint can be used in a given projection to link two nodes, it is a purely internal identifier and should
+     * be as performant as possible in queries, the current code uses UUIDs,
+     * so we will store the stringified UUID as binary for now.
+     *
+     * A simpler and faster format would be preferable though, int or a shorter binary format if possible. Fortunately
+     * this is a pure projection information and therefore could change by replay.
+     */
     public static function addColumnForNodeAnchorPoint(Table $table, string $columnName): Table
     {
         $table->addColumn($columnName, Types::BINARY)
@@ -44,6 +70,14 @@ public static function addColumnForNodeAnchorPoint(Table $table, string $columnN
         return $table;
     }
 
+    /**
+     * DimensionSpacePoints are PHP objects that need to be serialized as JSON, therefore we store them as TEXT for now,
+     * with a sensible collation for case insensitive text search.
+     *
+     * Using a dedicated JSON column format should be considered for the future.
+     *
+     * @see DimensionSpacePoint
+     */
     public static function addColumnForDimensionSpacePoint(Table $table, string $columnName, bool $notNull): Table
     {
         $table->addColumn($columnName, Types::TEXT)
@@ -54,6 +88,14 @@ public static function addColumnForDimensionSpacePoint(Table $table, string $col
         return $table;
     }
 
+    /**
+     * The hash for a given dimension space point for better query performance. As this is a hash, the size and type of
+     * content is deterministic, a binary type can be used as the actual content is not so important.
+     *
+     * We could imrpove by actually storing the hash in binary form and shortening and fixing the length.
+     *
+     * @see DimensionSpacePoint
+     */
     public static function addColumnForDimensionSpacePointHash(Table $table, string $columnName, bool $notNull): Table
     {
         $table->addColumn($columnName, Types::BINARY)
@@ -64,6 +106,11 @@ public static function addColumnForDimensionSpacePointHash(Table $table, string
         return $table;
     }
 
+    /**
+     * The NodeTypeName is an ascii string, we should be able to sort it properly, but we don't need unicode here.
+     *
+     * @see NodeTypeName
+     */
     public static function addColumnForNodeTypeName(Table $table, string $columnName): Table
     {
         $table->addColumn($columnName, Types::STRING)