From f7108b40c35c75028855e326ae55a7d6ffb5d97f Mon Sep 17 00:00:00 2001 From: Benjamin Eberlei Date: Tue, 10 Sep 2013 20:55:06 +0200 Subject: [PATCH] Move Annotations introduction to the reference. --- docs/en/reference/annotations-reference.rst | 26 ++++++++++++ docs/en/reference/basic-mapping.rst | 46 +++++++-------------- 2 files changed, 41 insertions(+), 31 deletions(-) diff --git a/docs/en/reference/annotations-reference.rst b/docs/en/reference/annotations-reference.rst index d42fda4e4..80ed01e7a 100644 --- a/docs/en/reference/annotations-reference.rst +++ b/docs/en/reference/annotations-reference.rst @@ -1,6 +1,32 @@ Annotations Reference ===================== +You've probably used docblock annotations in some form already, +most likely to provide documentation metadata for a tool like +``PHPDocumentor`` (@author, @link, ...). Docblock annotations are a +tool to embed metadata inside the documentation section which can +then be processed by some tool. Doctrine 2 generalizes the concept +of docblock annotations so that they can be used for any kind of +metadata and so that it is easy to define new docblock annotations. +In order to allow more involved annotation values and to reduce the +chances of clashes with other docblock annotations, the Doctrine 2 +docblock annotations feature an alternative syntax that is heavily +inspired by the Annotation syntax introduced in Java 5. + +The implementation of these enhanced docblock annotations is +located in the ``Doctrine\Common\Annotations`` namespace and +therefore part of the Common package. Doctrine 2 docblock +annotations support namespaces and nested annotations among other +things. The Doctrine 2 ORM defines its own set of docblock +annotations for supplying object-relational mapping metadata. + +.. note:: + + If you're not comfortable with the concept of docblock + annotations, don't worry, as mentioned earlier Doctrine 2 provides + XML and YAML alternatives and you could easily implement your own + favourite mechanism for defining ORM metadata. + In this chapter a reference of every Doctrine 2 Annotation is given with short explanations on their context and usage. diff --git a/docs/en/reference/basic-mapping.rst b/docs/en/reference/basic-mapping.rst index cfd06cd24..d21a4d007 100644 --- a/docs/en/reference/basic-mapping.rst +++ b/docs/en/reference/basic-mapping.rst @@ -1,10 +1,24 @@ Basic Mapping ============= -This chapter explains the basic mapping of objects and properties. +This guide explains the basic mapping of entities and properties. +After working through this guide you should know: + +- How to create PHP classes that can be saved in the database with Doctrine +- How to configure the mapping between columns on tables and properties on + entities. +- Defining primary keys and how identifiers are generated by Doctrine +- What Doctrine types are + Mapping of associations will be covered in the next chapter on :doc:`Association Mapping `. +Guide Assumptions +----------------- + +You should have already :doc:`installed and configure ` +Doctrine. + Mapping Drivers --------------- @@ -33,36 +47,6 @@ that explain them in more detail. There is also a reference chapter for cache (not recommended!) then the XML driver is the fastest by using PHP's native XML support. -Introduction to Docblock Annotations ------------------------------------- - -You've probably used docblock annotations in some form already, -most likely to provide documentation metadata for a tool like -``PHPDocumentor`` (@author, @link, ...). Docblock annotations are a -tool to embed metadata inside the documentation section which can -then be processed by some tool. Doctrine 2 generalizes the concept -of docblock annotations so that they can be used for any kind of -metadata and so that it is easy to define new docblock annotations. -In order to allow more involved annotation values and to reduce the -chances of clashes with other docblock annotations, the Doctrine 2 -docblock annotations feature an alternative syntax that is heavily -inspired by the Annotation syntax introduced in Java 5. - -The implementation of these enhanced docblock annotations is -located in the ``Doctrine\Common\Annotations`` namespace and -therefore part of the Common package. Doctrine 2 docblock -annotations support namespaces and nested annotations among other -things. The Doctrine 2 ORM defines its own set of docblock -annotations for supplying object-relational mapping metadata. - -.. note:: - - If you're not comfortable with the concept of docblock - annotations, don't worry, as mentioned earlier Doctrine 2 provides - XML and YAML alternatives and you could easily implement your own - favourite mechanism for defining ORM metadata. - - Persistent classes ------------------