add documentation about how to map column options

docs/en/reference/annotations-reference.rst

@@ -109,6 +109,26 @@ Optional attributes:
 
 -  **nullable**: Determines if NULL values allowed for this column.
 
+-  **options**: Array of additional options:
+
+   -  ``default``: The default value to set for the column if no value
+      is supplied.
+
+   -  ``unsigned``: Boolean value to determine if the column should
+      be capable of representing only non-negative integers
+      (applies only for integer column and might not be supported by
+      all vendors).
+
+   -  ``fixed``: Boolean value to determine if the specified length of
+      a string column should be fixed or varying (applies only for
+      string/binary column and might not be supported by all vendors).
+
+   -  ``comment``: The comment of the column in the schema (might not
+      be supported by all vendors).
+
+   -  ``customSchemaOptions``: Array of additional schema options
+      which are mostly vendor specific.
+
 -  **columnDefinition**: DDL SQL snippet that starts after the column
    name and specifies the complete (non-portable!) column definition.
    This attribute allows to make use of advanced RMDBS features.
@@ -122,6 +142,11 @@ Optional attributes:
    joins between tables you should also take a look at
    :ref:`@JoinColumn <annref_joincolumn>`.
 
+.. note::
+
+    For more detailed information on each attribute, please refer to
+    the DBAL ``Schema-Representation`` documentation.
+
 Examples:
 
 .. code-block:: php
@@ -142,6 +167,16 @@ Examples:
      */
     protected $height;
 
+    /**
+     * @Column(type="string", length=2, options={"fixed":true, "comment":"Initial letters of first and last name"})
+     */
+    protected $initials;
+
+    /**
+     * @Column(type="integer", name="login_count" nullable=false, options={"unsigned":true, "default":0})
+     */
+    protected $loginCount;
+
 .. _annref_column_result:
 
 @ColumnResult

docs/en/reference/php-mapping.rst

@@ -51,7 +51,21 @@ named ``Entities.User.php`` inside of the
 
     $metadata->mapField(array(
        'fieldName' => 'username',
-       'type' => 'string'
+       'type' => 'string',
+       'options' => array(
+           'fixed' => true,
+           'comment' => "User's login name"
+       )
+    ));
+
+    $metadata->mapField(array(
+       'fieldName' => 'login_count',
+       'type' => 'integer',
+       'nullable' => false,
+       'options' => array(
+           'unsigned' => true,
+           'default' => 0
+       )
     ));
 
 Now we can easily retrieve the populated ``ClassMetadata`` instance

docs/en/reference/xml-mapping.rst

@@ -230,6 +230,12 @@ entity. For the ID mapping you have to use the ``<id />`` element.
         <field name="age" type="integer" nullable="true" />
         <field name="isActive" column="is_active" type="boolean" />
         <field name="weight" type="decimal" scale="5" precision="2" />
+        <field name="login_count" type="integer" nullable="false">
+            <options>
+                <option name="comment">The number of times the user has logged in.</option>
+                <option name="default">0</option>
+            </options>
+        </field>
     </entity>
 
 Required attributes:
@@ -255,12 +261,32 @@ Optional attributes:
    works on fields with type integer or datetime.
 -  scale - Scale of a decimal type.
 -  precision - Precision of a decimal type.
+-  options - Array of additional options:
+
+   -  default - The default value to set for the column if no value
+      is supplied.
+   -  unsigned - Boolean value to determine if the column should
+      be capable of representing only non-negative integers
+      (applies only for integer column and might not be supported by
+      all vendors).
+   -  fixed - Boolean value to determine if the specified length of
+      a string column should be fixed or varying (applies only for
+      string/binary column and might not be supported by all vendors).
+   -  comment - The comment of the column in the schema (might not
+      be supported by all vendors).
+   -  customSchemaOptions - Array of additional schema options
+      which are mostly vendor specific.
 -  column-definition - Optional alternative SQL representation for
    this column. This definition begin after the field-name and has to
    specify the complete column definition. Using this feature will
    turn this field dirty for Schema-Tool update commands at all
    times.
 
+.. note::
+
+    For more detailed information on each attribute, please refer to
+    the DBAL ``Schema-Representation`` documentation.
+
 Defining Identity and Generator Strategies
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/en/reference/yaml-mapping.rst

@@ -94,6 +94,14 @@ of several common elements:
           unique: true
           options:
             fixed: true
+            comment: User's email address
+        loginCount:
+          type: integer
+          column: login_count
+          nullable: false
+          options:
+            unsigned: true
+            default: 0
       oneToOne:
         address:
           targetEntity: Address