Cleaned up documentation

[caponica]

Cleaned up documentation, tweaked some of the grammar, edits for improved readability, changed class#method() references to class::method(), added warning about performance impact of lazy loading

[doctrinebot]

Hello,

thank you for creating this pull request. I have automatically opened an issue
on our Jira Bug Tracker for you. See the issue link:

http://www.doctrine-project.org/jira/browse/DDC-2571

We use Jira to track the state of pull requests and the versions they got
included in.

[Ocramius]

We actually use # for non-static calls. :: is used only for static method calls (yes, using :: for both is a bad practice of the php community)

[caponica]

I don't think the page is consistent... it uses EntityManager#find() (which requires an instance of EntityManager) and also User::addReportedBug() (which also requires an instance...)

I put this question on stackexchange and the general suggestion from the community was to avoid using # (since it's not a generally recognised standard) and just stick to :: in all cases.

[Ocramius]

@caponica agreed on what the community does, not agreeing that the community does it right :)

[caponica]

Well, if we're going to use # for non-static calls we should at least be consistent ourselves! I'll update the whole doc to change all the relevant documentation references from :: to # when I get a chance and then update the PR.

[Ocramius]

@caponica agreed, and thanks :)

[caponica]

Do you also want to use this notation for class properties, e.g. should it be Product::$name, Product#$name, Product::name or Product#name?

[Ocramius]

@caponica not sure to be honest. @guilhermeblanco ?

[caponica]

(by the way, I have to agree with the peeps on stackexchange that using a # is really weird in a PHP context, but I'll go with whatever house style you prefer!)

[caponica]

A couple of other comments about this page of the documentation are below. Either I'm not bright enough to understand what's happening in them all, or they seem to be inconsistent with the code displayed.

---

The following paragraph is quite opaque and does not explain itself very well:

Note how the properties have getter and setter methods defined except $id. To access data 
from entities Doctrine 2 uses the Reflection API, so it is possible for Doctrine to access the 
value of $id. You don’t have to take Doctrine into account when designing access to the 
state of your objects.

---

I cannot see where the column names have been changed/set:

The column names are used from the Zend_Db_Table examples and have different names 
than the properties on the Bug class.

---

This paragraph seems confusing, since the join definition is simply <many-to-many target-entity="Product" field="products" />

The last missing property is the Bug::$products collection. It holds all products where the 
specific bug is occurring in. Again you have to define the target-entity and field attributes 
on the many-to-many tag. Furthermore you have to specify the details of the many-to-many 
join-table and its foreign key columns. The definition is rather complex, however relying on 
the XML auto-completion I got it working easily, although I forget the schema details all 
the time.

[Ocramius]

First paragraph should be like this:

Note how a getter and setter were defined for each property except for $id. To manipulate data
in your entities, Doctrine 2 uses the Reflection API, so it is possible for Doctrine to access the
value of $id even if no public API does allow that.
You don’t have to take Doctrine into account when designing access to the state of your objects.

[Ocramius]

Not sure about the second paragraph (where is it located?)

Third paragraph looks like a personal thought. It could be manipulated to state that an additional number of properties and settings can be added to the many-to-many mapping

[caponica]

Hi, you can view the current version of this here: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/tutorials/getting-started.html

I'll work on tidying up the first paragraph.

The second paragraph appears after the following block of XML code, which I don't think has any specially defined column names (it just uses the defaults as far as I can see):

<!-- config/xml/Bug.dcm.xml -->
<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                    http://raw.github.com/doctrine/doctrine2/master/doctrine-mapping.xsd">

    <entity name="Bug" table="bugs">
        <id name="id" type="integer">
            <generator strategy="AUTO" />
        </id>

        <field name="description" type="text" />
        <field name="created" type="datetime" />
        <field name="status" type="string" />

        <many-to-one target-entity="User" field="reporter" inversed-by="reportedBugs" />
        <many-to-one target-entity="User" field="engineer" inversed-by="assignedBugs" />

        <many-to-many target-entity="Product" field="products" />
    </entity>
</doctrine-mapping>

The third paragraph is confusing (me!) since it talks about the complexity of defining the products relationship, but that relationship is actually just a simple many-to-many join. Maybe the paragraph should just be removed?

[guilhermeblanco]

@Ocramius @caponica Doctrine uses # for instance and :: for static.
This means: EntityManager#find(), Entity#name, Query::HINT_FOO.

[caponica]

OK, I've cleaned up the references to the class properties to use the Entity#name style (instead of Entity::$name) and rewritten the three paragraphs that I think were a bit confusing. I think this is now ready to merge in but let me know if there's anything else to fix!

[beberlei]

Thank you for this!