DDC-1089: Annotations reference examples are inaccurate and confusing #1365

New Issue

admin · 2026-01-22T13:11:53+01:00

admin commented

2026-01-22 13:11:53 +01:00

Originally created by @doctrinebot on GitHub (Mar 30, 2011).

Originally assigned to: @Ocramius on GitHub.

Jira issue originally created by user mvl:

In chapter 19 of the reference guide some coding examples seem to be inaccurate or incorrect. Especially when it comes to the bidirectional many-to-many associations, this might be confusing.

Example:
The code fragment on http://www.doctrine-project.org/docs/orm/2.0/en/reference/annotations-reference.html#annref-manytomany has the following issues:

it does not include class declarations although the collections associated are both mentioned. It should be clear to which target entity they belong and therefore their classes should be declared.
from the context it seems that the associated classes should probably be User and Group, and the owning side is User. So the association should probably be inversed by 'users', although the example mentions 'features'.
the mapping for the inverse side maps a collection called $features, although this should probably be $users. Also the class declaration for the Group class is missing.

Some other code fragments in chapter 19 have similar issues. I think they could easily be replaced by the examples from the earlier chapters, like for the bidirectional man-to-many association the example from chapter 5:

http://www.doctrine-project.org/docs/orm/2.0/en/reference/association-mapping.html#many-to-many-bidirectional

Originally created by @doctrinebot on GitHub (Mar 30, 2011). Originally assigned to: @Ocramius on GitHub. Jira issue originally created by user mvl: In chapter 19 of the reference guide some coding examples seem to be inaccurate or incorrect. Especially when it comes to the bidirectional many-to-many associations, this might be confusing. Example: The code fragment on http://www.doctrine-project.org/docs/orm/2.0/en/reference/annotations-reference.html#annref-manytomany has the following issues: - it does not include class declarations although the collections associated are both mentioned. It should be clear to which target entity they belong and therefore their classes should be declared. - from the context it seems that the associated classes should probably be User and Group, and the owning side is User. So the association should probably be inversed by 'users', although the example mentions 'features'. - the mapping for the inverse side maps a collection called $features, although this should probably be $users. Also the class declaration for the Group class is missing. Some other code fragments in chapter 19 have similar issues. I think they could easily be replaced by the examples from the earlier chapters, like for the bidirectional man-to-many association the example from chapter 5: http://www.doctrine-project.org/docs/orm/2.0/en/reference/association-mapping.html#many-to-many-bidirectional

admin added the Documentation Invalid Incomplete labels 2026-01-22 13:11:53 +01:00

admin closed this issue

2026-01-22 13:11:54 +01:00

admin commented

2026-01-22 13:11:54 +01:00

@billschaller commented on GitHub (Jan 6, 2016):

This is a somewhat valid qualm with the annotation reference docs. The mappings are pretty well documented elsewhere, and this is mostly intended as a reference for usage of the annotations themselves though. As for the cited @ManyToMany example, it appears the inverse side is called $features while the inverse fk is user_id. The inverse fk should probably be called feature_id. I don't think it's necessary to have a full class decl, but splitting the code block would make sense.

The annotation reference has improved quite a bit since this ticket was logged. I don't think much action is warranted here.

@billschaller commented on GitHub (Jan 6, 2016): This is a somewhat valid qualm with the annotation reference docs. The mappings are pretty well documented elsewhere, and this is mostly intended as a reference for usage of the annotations themselves though. As for the cited @ManyToMany example, it appears the inverse side is called $features while the inverse fk is user_id. The inverse fk should probably be called feature_id. I don't think it's necessary to have a full class decl, but splitting the code block would make sense. The annotation reference has improved quite a bit since this ticket was logged. I don't think much action is warranted here.

admin commented

2026-01-22 13:11:55 +01:00

@malukenho commented on GitHub (Jan 12, 2017):

@lcobucci ca be closed as documentation was improved since then.

@malukenho commented on GitHub (Jan 12, 2017): @lcobucci ca be closed as documentation was improved since then.

admin referenced this issue

2026-01-22 16:04:17 +01:00

[PR #1365] fix rare query test failures due to nondeterminism without order by clause #9425

Sign in to join this conversation.