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

Clarify that some interface are not meant to be implemented

5 files changed, 37 insertions, 3 deletions

diff --git a/lib/public/DB/IPreparedStatement.php b/lib/public/DB/IPreparedStatement.php
index 2fadff5da3f..391f987d20a 100644
--- a/lib/public/DB/IPreparedStatement.php
+++ b/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 {
diff --git a/lib/public/DB/IResult.php b/lib/public/DB/IResult.php
index 76f8cf26601..cbed1e51dac 100644
--- a/lib/public/DB/IResult.php
+++ b/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 {
diff --git a/lib/public/DB/ISchemaWrapper.php b/lib/public/DB/ISchemaWrapper.php
index 82e4205f1b3..5c7ebaa7c30 100644
--- a/lib/public/DB/ISchemaWrapper.php
+++ b/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
  */
diff --git a/lib/public/Share/IManager.php b/lib/public/Share/IManager.php
index 8b1f5144b9a..ff4b6af19e0 100644
--- a/lib/public/Share/IManager.php
+++ b/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
  */
diff --git a/lib/public/UserStatus/IManager.php b/lib/public/UserStatus/IManager.php
index f709768d717..354a1e19ee9 100644
--- a/lib/public/UserStatus/IManager.php
+++ b/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
  */