Merge pull request #31447 from nextcloud/doc/manager-interface

Clarify that some interface are not meant to be implemented

lib/public/DB/IPreparedStatement.php

@@ -30,6 +30,15 @@ use Doctrine\DBAL\ParameterType;
 use PDO;
 
 /**
+ * This interface allows you to prepare a database query.
+ *
+ * This interface must not be implemented in your application but
+ * instead obtained from IDBConnection::prepare.
+ *
+ * ```php
+ * $prepare = $this->db->prepare($query->getSql());
+ * ```
+ *
  * @since 21.0.0
  */
 interface IPreparedStatement {

lib/public/DB/IResult.php

@@ -29,6 +29,18 @@ namespace OCP\DB;
 use PDO;
 
 /**
+ * This interface represents the result of a database query.
+ *
+ * Usage:
+ *
+ * ```php
+ * $qb = $this->db->getQueryBuilder();
+ * $qb->select(...);
+ * $result = $query->executeQuery();
+ * ```
+ *
+ * This interface must not be implemented in your application.
+ *
  * @since 21.0.0
  */
 interface IResult {

lib/public/DB/ISchemaWrapper.php

@@ -26,7 +26,12 @@ use Doctrine\DBAL\Exception;
 use Doctrine\DBAL\Platforms\AbstractPlatform;
 
 /**
- * Interface ISchemaWrapper
+ * This interface allows to get information about the database schema.
+ * This is particularly helpful for database migration scripts.
+ *
+ * This interface must not be implemented in your application but
+ * instead can be obtained in your migration scripts with the
+ * `$schemaClosure` Closure.
  *
  * @since 13.0.0
  */

lib/public/Share/IManager.php

@@ -37,7 +37,11 @@ use OCP\Share\Exceptions\GenericShareException;
 use OCP\Share\Exceptions\ShareNotFound;
 
 /**
- * Interface IManager
+ * This interface allows to manage sharing files between users and groups.
+ *
+ * This interface must not be implemented in your application but
+ * instead should be used as a service and injected in your code with
+ * dependency injection.
  *
  * @since 9.0.0
  */

lib/public/UserStatus/IManager.php

@@ -26,7 +26,11 @@ declare(strict_types=1);
 namespace OCP\UserStatus;
 
 /**
- * Interface IManager
+ * This interface allows to manage the user status.
+ *
+ * This interface must not be implemented in your application but
+ * instead should be used as a service and injected in your code with
+ * dependency injection.
  *
  * @since 20.0.0
  */