diff --git a/lib/private/Config.php b/lib/private/Config.php
index ec380aedc5d..44a26a16777 100644
--- a/lib/private/Config.php
+++ b/lib/private/Config.php
@@ -268,8 +268,25 @@ class Config {
 		}
 
 		// Create a php file ...
-		$content = "<?php\n";
-		$content .= '$CONFIG = ';
+		$content = "<?php
+
+/*
+ * WARNING
+ *
+ * This file gets modified by automatic processes and all lines that are not
+ * active code (ie. comments) are lost during that process.
+ *
+ * If you want to document things with comments or use constants add your settings
+ * in a '<NAME>.config.php' file which will be included and rendered into this file.
+ *
+ * Example:
+ *   <?php
+ *   \$CONFIG = [];
+ *
+ * See also: https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#multiple-merged-configuration-files
+ */
+
+\$CONFIG = ";
 		$content .= var_export(self::trustSystemConfig($this->cache), true);
 		$content .= ";\n";
 
diff --git a/tests/lib/ConfigTest.php b/tests/lib/ConfigTest.php
index b2a52dbd6a4..3ef54f7644f 100644
--- a/tests/lib/ConfigTest.php
+++ b/tests/lib/ConfigTest.php
@@ -97,7 +97,26 @@ class ConfigTest extends TestCase {
 		$this->assertSame('moo', $config->getValue('foo'));
 
 		$content = file_get_contents($this->configFile);
-		$expected = "<?php\n\$CONFIG = array (\n  'foo' => 'moo',\n  'beers' => \n  array (\n    0 => 'Appenzeller',\n  "
+		$expected = "<?php
+
+/*
+ * WARNING
+ *
+ * This file gets modified by automatic processes and all lines that are not
+ * active code (ie. comments) are lost during that process.
+ *
+ * If you want to document things with comments or use constants add your settings
+ * in a '<NAME>.config.php' file which will be included and rendered into this file.
+ *
+ * Example:
+ *   <?php
+ *   \$CONFIG = [];
+ *
+ * See also: https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#multiple-merged-configuration-files
+ */
+
+";
+		$expected .= "\$CONFIG = array (\n  'foo' => 'moo',\n  'beers' => \n  array (\n    0 => 'Appenzeller',\n  "
 			. "  1 => 'Guinness',\n    2 => 'Kölsch',\n  ),\n  'alcohol_free' => false,\n);\n";
 		$this->assertEquals($expected, $content);
 
@@ -108,7 +127,26 @@ class ConfigTest extends TestCase {
 
 		$content = file_get_contents($this->configFile);
 
-		$expected = "<?php\n\$CONFIG = array (\n  'foo' => 'moo',\n  'beers' => \n  array (\n    0 => 'Appenzeller',\n  "
+		$expected = "<?php
+
+/*
+ * WARNING
+ *
+ * This file gets modified by automatic processes and all lines that are not
+ * active code (ie. comments) are lost during that process.
+ *
+ * If you want to document things with comments or use constants add your settings
+ * in a '<NAME>.config.php' file which will be included and rendered into this file.
+ *
+ * Example:
+ *   <?php
+ *   \$CONFIG = [];
+ *
+ * See also: https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#multiple-merged-configuration-files
+ */
+
+";
+		$expected .= "\$CONFIG = array (\n  'foo' => 'moo',\n  'beers' => \n  array (\n    0 => 'Appenzeller',\n  "
 			. "  1 => 'Guinness',\n    2 => 'Kölsch',\n  ),\n  'alcohol_free' => false,\n  'bar' => 'red',\n  'apps' => \n "
 			. " array (\n    0 => 'files',\n    1 => 'gallery',\n  ),\n);\n";
 		$this->assertEquals($expected, $content);
@@ -139,7 +177,26 @@ class ConfigTest extends TestCase {
 		$this->assertSame(null, $config->getValue('not_exists'));
 
 		$content = file_get_contents($this->configFile);
-		$expected = "<?php\n\$CONFIG = array (\n  'foo' => 'moo',\n  'beers' => \n  array (\n    0 => 'Appenzeller',\n  "
+		$expected = "<?php
+
+/*
+ * WARNING
+ *
+ * This file gets modified by automatic processes and all lines that are not
+ * active code (ie. comments) are lost during that process.
+ *
+ * If you want to document things with comments or use constants add your settings
+ * in a '<NAME>.config.php' file which will be included and rendered into this file.
+ *
+ * Example:
+ *   <?php
+ *   \$CONFIG = [];
+ *
+ * See also: https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#multiple-merged-configuration-files
+ */
+
+";
+		$expected .= "\$CONFIG = array (\n  'foo' => 'moo',\n  'beers' => \n  array (\n    0 => 'Appenzeller',\n  "
 			. "  1 => 'Guinness',\n    2 => 'Kölsch',\n  ),\n);\n";
 		$this->assertEquals($expected, $content);
 	}
@@ -150,7 +207,26 @@ class ConfigTest extends TestCase {
 		$this->assertSame('this_was_clearly_not_set_before', $config->getValue('foo', 'this_was_clearly_not_set_before'));
 		$content = file_get_contents($this->configFile);
 
-		$expected = "<?php\n\$CONFIG = array (\n  'beers' => \n  array (\n    0 => 'Appenzeller',\n  "
+		$expected = "<?php
+
+/*
+ * WARNING
+ *
+ * This file gets modified by automatic processes and all lines that are not
+ * active code (ie. comments) are lost during that process.
+ *
+ * If you want to document things with comments or use constants add your settings
+ * in a '<NAME>.config.php' file which will be included and rendered into this file.
+ *
+ * Example:
+ *   <?php
+ *   \$CONFIG = [];
+ *
+ * See also: https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#multiple-merged-configuration-files
+ */
+
+";
+		$expected .= "\$CONFIG = array (\n  'beers' => \n  array (\n    0 => 'Appenzeller',\n  "
 			. "  1 => 'Guinness',\n    2 => 'Kölsch',\n  ),\n  'alcohol_free' => false,\n);\n";
 		$this->assertEquals($expected, $content);
 	}
@@ -170,7 +246,26 @@ class ConfigTest extends TestCase {
 
 		// Write a new value to the config
 		$config->setValue('CoolWebsites', ['demo.owncloud.org', 'owncloud.org', 'owncloud.com']);
-		$expected = "<?php\n\$CONFIG = array (\n  'foo' => 'bar',\n  'beers' => \n  array (\n    0 => 'Appenzeller',\n  "
+		$expected = "<?php
+
+/*
+ * WARNING
+ *
+ * This file gets modified by automatic processes and all lines that are not
+ * active code (ie. comments) are lost during that process.
+ *
+ * If you want to document things with comments or use constants add your settings
+ * in a '<NAME>.config.php' file which will be included and rendered into this file.
+ *
+ * Example:
+ *   <?php
+ *   \$CONFIG = [];
+ *
+ * See also: https://docs.nextcloud.com/server/latest/admin_manual/configuration_server/config_sample_php_parameters.html#multiple-merged-configuration-files
+ */
+
+";
+		$expected .= "\$CONFIG = array (\n  'foo' => 'bar',\n  'beers' => \n  array (\n    0 => 'Appenzeller',\n  "
 			. "  1 => 'Guinness',\n    2 => 'Kölsch',\n  ),\n  'alcohol_free' => false,\n  'php53' => 'totallyOutdated',\n  'CoolWebsites' => \n  array (\n  "
 			. "  0 => 'demo.owncloud.org',\n    1 => 'owncloud.org',\n    2 => 'owncloud.com',\n  ),\n);\n";
 		$this->assertEquals($expected, file_get_contents($this->configFile));