Merge pull request #9355 from nextcloud/enhancement/codeblock-caption-file-name

Use captions to better highlight codeblock file names

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
 

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"

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;