From deb51a5240f384cf3f5169d15620449c27bff0ec Mon Sep 17 00:00:00 2001
From: Christoph Wurst <christoph@winzerhof-wurst.at>
Date: Mon, 14 Nov 2022 15:21:36 +0100
Subject: [PATCH] Use captions to better highlight codeblock file names

Signed-off-by: Christoph Wurst <christoph@winzerhof-wurst.at>
---
 developer_manual/app_development/bootstrap.rst |  5 +++++
 developer_manual/app_development/info.rst      |  2 ++
 developer_manual/basics/storage/database.rst   | 15 +++++++++------
 3 files changed, 16 insertions(+), 6 deletions(-)

diff --git a/developer_manual/app_development/bootstrap.rst b/developer_manual/app_development/bootstrap.rst
index 9c57b6861..8ccf3eb4b 100644
--- a/developer_manual/app_development/bootstrap.rst
+++ b/developer_manual/app_development/bootstrap.rst
@@ -44,6 +44,7 @@ Nextcloud will try to autoload the class from the namespace ``\OCA\<App namespac
 The class **must** extend ``OCP\AppFramework\App`` and may optionally implement ``\OCP\AppFramework\Bootstrap\IBootstrap``:
 
 .. code-block:: php
+    :caption: lib/AppInfo/Application.php
 
     <?php
 
@@ -127,6 +128,7 @@ Booting an app
 Any code that should run once for every Nextcloud process goes into the ``boot`` method of an app's ``Application`` class. Use this mechanism carefully as it could have a negative effect on Nextcloud's overall performance.
 
 .. code-block:: php
+    :caption: lib/AppInfo/Application.php
     :emphasize-lines: 11-15
 
     <?php
@@ -150,6 +152,7 @@ Any code that should run once for every Nextcloud process goes into the ``boot``
 The code above fetches a fictional *foo manager* to register an app class. The boot context object comes with a ``injectFn`` helper that eases dependency injection inside the ``boot`` method by injecting arguments of a callable:
 
 .. code-block:: php
+    :caption: lib/AppInfo/Application.php
     :emphasize-lines: 12-14
 
     <?php
@@ -173,6 +176,7 @@ The code above fetches a fictional *foo manager* to register an app class. The b
 With the help of ``Closure::fromCallable`` you can also delegate to other methods that get their arguments injected:
 
 .. code-block:: php
+    :caption: lib/AppInfo/Application.php
     :emphasize-lines: 12,15-17
 
     <?php
@@ -215,6 +219,7 @@ To leverage the advantages of object-oriented programming, it's recommended to p
 class and query an instance like
 
 .. code-block:: php
+    :caption: appinfo/app.php
 
     <?php
 
diff --git a/developer_manual/app_development/info.rst b/developer_manual/app_development/info.rst
index 2984d4ef6..a90b95bb3 100644
--- a/developer_manual/app_development/info.rst
+++ b/developer_manual/app_development/info.rst
@@ -13,6 +13,7 @@ The info.xml is validated using an XML Schema which can be accessed `online <htt
 A minimum valid **info.xml** would look like this:
 
 .. code-block:: xml
+    :caption: appinfo/info.xml
 
     <?xml version="1.0"?>
     <info xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance"
@@ -34,6 +35,7 @@ A minimum valid **info.xml** would look like this:
 A full blown example would look like this (needs to be utf-8 encoded):
 
 .. code-block:: xml
+    :caption: appinfo/info.xml
 
     <?xml version="1.0"?>
     <info xmlns:xsi= "http://www.w3.org/2001/XMLSchema-instance"
diff --git a/developer_manual/basics/storage/database.rst b/developer_manual/basics/storage/database.rst
index 589305eca..5026eead1 100644
--- a/developer_manual/basics/storage/database.rst
+++ b/developer_manual/basics/storage/database.rst
@@ -9,9 +9,9 @@ The basic way to run a database query is to use the database connection provided
 Inside your database layer class you can now start running queries like:
 
 .. code-block:: php
+    :caption: lib/Db/AuthorDAO.php
 
     <?php
-    // db/authordao.php
 
     namespace OCA\MyApp\Db;
 
@@ -128,9 +128,9 @@ To create a mapper, inherit from the mapper base class and call the parent const
 * **Optional**: Entity class name, defaults to \\OCA\\MyApp\\Db\\Author in the example below
 
 .. code-block:: php
+    :caption: lib/Db/AthorMapper.php
 
     <?php
-    // db/authormapper.php
 
     namespace OCA\MyApp\Db;
 
@@ -213,9 +213,10 @@ Entities are data objects that carry all the table's information for one row. Ev
 * **Property name**: phoneNumber
 
 .. code-block:: php
+    :caption: lib/Db/Author.php
 
     <?php
-    // db/author.php
+
     namespace OCA\MyApp\Db;
 
     use OCP\AppFramework\Db\Entity;
@@ -255,8 +256,10 @@ Since all attributes should be protected, getters and setters are automatically
 
 .. code-block:: php
 
+    :caption: lib/Db/Author.php
+
     <?php
-    // db/author.php
+
     namespace OCA\MyApp\Db;
 
     use OCP\AppFramework\Db\Entity;
@@ -280,10 +283,10 @@ different columns because of backwards compatibility. To define a custom
 mapping, simply override the **columnToProperty** and **propertyToColumn** methods of the entity in question:
 
 .. code-block:: php
-
+    :caption: lib/Db/Author.php
 
     <?php
-    // db/author.php
+
     namespace OCA\MyApp\Db;
 
     use OCP\AppFramework\Db\Entity;