Mark methods and classes as internal

UPGRADE-2.0.md

@@ -297,3 +297,13 @@ ocramius. If you are checking for proxies, the following changed:
 * The `isScheduledForDirtyCheck` and `scheduleForDirtyCheck` methods have been
   renamed to `isScheduledForSynchronization` and `scheduleForSynchronization`,
   respectively.
+
+## Internal classes and methods
+
+Number of public methods and classes saw an `@internal` annotation added. This
+marks places which are considered private to ODM but can not become ones due to
+language limitations. Those methods can still be used (at your own risk) however
+the backward compatibility promise for them is relaxed: we reserve the right to
+change internal method's signatures and/or remove them altogether in *minor*
+releases. Should such change be made, a note shall be included in the `UPGRADE.md`
+file describing changes contained in the release.

lib/Doctrine/ODM/MongoDB/Hydrator/HydratorFactory.php

@@ -107,6 +107,8 @@ public function __construct(DocumentManager $dm, EventManager $evm, ?string $hyd
 
     /**
      * Sets the UnitOfWork instance.
+     *
+     * @internal
      */
     public function setUnitOfWork(UnitOfWork $uow) : void
     {

lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadata.php

@@ -573,8 +573,9 @@ public function isIdentifier($fieldName) : bool
     }
 
     /**
-     * INTERNAL:
      * Sets the mapped identifier field of this class.
+     *
+     * @internal
      */
     public function setIdentifier(?string $identifier) : void
     {
@@ -1249,9 +1250,10 @@ public function mapManyReference(array $mapping) : void
     }
 
     /**
-     * INTERNAL:
      * Adds a field mapping without completing/validating it.
      * This is mainly used to add inherited field mappings to derived classes.
+     *
+     * @internal
      */
     public function addInheritedFieldMapping(array $fieldMapping) : void
     {
@@ -1265,10 +1267,11 @@ public function addInheritedFieldMapping(array $fieldMapping) : void
     }
 
     /**
-     * INTERNAL:
      * Adds an association mapping without completing/validating it.
      * This is mainly used to add inherited association mappings to derived classes.
      *
+     * @internal
+     *
      * @throws MappingException
      */
     public function addInheritedAssociationMapping(array $mapping) : void

lib/Doctrine/ODM/MongoDB/Mapping/ClassMetadataFactory.php

@@ -30,6 +30,8 @@
  * The ClassMetadataFactory is used to create ClassMetadata objects that contain all the
  * metadata mapping informations of a class which describes how a class should be mapped
  * to a document database.
+ *
+ * @internal
  */
 class ClassMetadataFactory extends AbstractClassMetadataFactory
 {

lib/Doctrine/ODM/MongoDB/PersistentCollection/PersistentCollectionInterface.php

@@ -71,14 +71,12 @@ public function isDirty();
     public function setDirty($dirty);
 
     /**
-     * INTERNAL:
      * Sets the collection's owning entity together with the AssociationMapping that
      * describes the association between the owner and the elements of the collection.
      */
     public function setOwner(object $document, array $mapping);
 
     /**
-     * INTERNAL:
      * Tells this collection to take a snapshot of its current state reindexing
      * itself numerically if using save strategy that is enforcing BSON array.
      * Reindexing is safe as snapshot is taken only after synchronizing collection
@@ -87,52 +85,43 @@ public function setOwner(object $document, array $mapping);
     public function takeSnapshot();
 
     /**
-     * INTERNAL:
      * Clears the internal snapshot information and sets isDirty to true if the collection
      * has elements.
      */
     public function clearSnapshot();
 
     /**
-     * INTERNAL:
      * Returns the last snapshot of the elements in the collection.
      *
      * @return array The last snapshot of the elements.
      */
     public function getSnapshot();
 
     /**
-     * INTERNAL:
-     * getDeleteDiff
-     *
      * @return array
      */
     public function getDeleteDiff();
 
     /**
-     * INTERNAL: get objects that were removed, unlike getDeleteDiff this doesn't care about indices.
+     * Get objects that were removed, unlike getDeleteDiff this doesn't care about indices.
      *
      * @return array
      */
     public function getDeletedDocuments();
 
     /**
-     * INTERNAL:
-     * getInsertDiff
-     *
      * @return array
      */
     public function getInsertDiff();
 
     /**
-     * INTERNAL: get objects that were added, unlike getInsertDiff this doesn't care about indices.
+     * Get objects that were added, unlike getInsertDiff this doesn't care about indices.
      *
      * @return array
      */
     public function getInsertedDocuments();
 
     /**
-     * INTERNAL:
      * Gets the collection owner.
      */
     public function getOwner() : ?object;

lib/Doctrine/ODM/MongoDB/Persisters/CollectionPersister.php

@@ -38,6 +38,8 @@
  * removed, CollectionPersister::update() will be called, which may set the
  * entire collection or delete/insert individual elements, depending on the
  * mapping strategy.
+ *
+ * @internal
  */
 class CollectionPersister
 {

lib/Doctrine/ODM/MongoDB/Persisters/DocumentPersister.php

@@ -62,6 +62,8 @@
 
 /**
  * The DocumentPersister is responsible for persisting documents.
+ *
+ * @internal
  */
 class DocumentPersister
 {

lib/Doctrine/ODM/MongoDB/Persisters/PersistenceBuilder.php

@@ -21,6 +21,8 @@
  * PersistenceBuilder builds the queries used by the persisters to update and insert
  * documents when a DocumentManager is flushed. It uses the changeset information in the
  * UnitOfWork to build queries using atomic operators like $set, $unset, etc.
+ *
+ * @internal
  */
 class PersistenceBuilder
 {

lib/Doctrine/ODM/MongoDB/Proxy/FileLocator.php

@@ -8,6 +8,9 @@
 use function mkdir;
 use function realpath;
 
+/**
+ * @internal
+ */
 final class FileLocator extends BaseFileLocator
 {
     public function __construct(string $proxiesDirectory)

lib/Doctrine/ODM/MongoDB/Query/QueryExpressionVisitor.php

@@ -13,6 +13,8 @@
 
 /**
  * Converts Collection expressions to query expressions.
+ *
+ * @internal
  */
 class QueryExpressionVisitor extends ExpressionVisitor
 {

lib/Doctrine/ODM/MongoDB/Query/ReferencePrimer.php

@@ -37,6 +37,8 @@
  *
  * Priming can only be used for the owning side side of a relationship, since
  * the referenced identifiers are not immediately available on an inverse side.
+ *
+ * @internal
  */
 class ReferencePrimer
 {