Added more help notes in the application code

javiereguiluz · javiereguiluz · commit 5fa38221a84c · 2015-04-24T10:45:00.000+02:00
diff --git a/app/AppKernel.php b/app/AppKernel.php
@@ -7,6 +7,10 @@ class AppKernel extends Kernel
 {
     public function registerBundles()
     {
+        // When you install a third-party bundle or create a new bundle in your
+        // application, you must add it in the following array to register it
+        // in the application. Otherwise, the bundle won't be enabled and you
+        // won't be able to use it.
         $bundles = array(
             new Symfony\Bundle\FrameworkBundle\FrameworkBundle(),
             new Symfony\Bundle\SecurityBundle\SecurityBundle(),
@@ -20,6 +24,10 @@ public function registerBundles()
             new AppBundle\AppBundle(),
         );
 
+        // Some bundles are only used while developing the application or during
+        // the unit and functional tests. Therefore, they are only registered
+        // when the application runs in 'dev' or 'test' environments. This allows
+        // to increase application performance in the production environment.
         if (in_array($this->getEnvironment(), array('dev', 'test'))) {
             $bundles[] = new Symfony\Bundle\DebugBundle\DebugBundle();
             $bundles[] = new Symfony\Bundle\WebProfilerBundle\WebProfilerBundle();
diff --git a/app/Resources/views/admin/layout.html.twig b/app/Resources/views/admin/layout.html.twig
@@ -1,3 +1,10 @@
+{#
+   This is the base template of the all backend pages. Since this layout is similar
+   to the global layout, we inherit from it to just change the contents of some
+   blocks. In practice, backend templates are using a three-level inheritance,
+   showing how powerful, yet easy to use, is Twig's inheritance mechanism.
+   See http://symfony.com/doc/current/book/templating.html#template-inheritance-and-layouts
+#}
 {% extends 'base.html.twig' %}
 
 {% block header_navigation_links %}
diff --git a/app/Resources/views/base.html.twig b/app/Resources/views/base.html.twig
@@ -1,3 +1,8 @@
+{#
+   This is the base template used as the application layout which contains the
+   common elements and decorates all the other templates.
+   See http://symfony.com/doc/current/book/templating.html#template-inheritance-and-layouts
+#}
 <!DOCTYPE html>
 <html>
     <head>
diff --git a/app/Resources/views/default/_source_code.html.twig b/app/Resources/views/default/_source_code.html.twig
@@ -1,3 +1,11 @@
+{#
+   This is a template fragment designed to be included in other templates
+   See http://symfony.com/doc/current/book/templating.html#including-other-templates
+
+   A common practice to better distinguish between templates and fragments is to
+   prefix fragments with an underscore. That's why this template is called
+   '_source_code.html.twig' instead of 'source_code.html.twig'
+#}
 <div class="section source-code">
     <p>
         Click on this button to show the source code of the <strong>Controller</strong>
diff --git a/src/AppBundle/Controller/Admin/BlogController.php b/src/AppBundle/Controller/Admin/BlogController.php
@@ -22,6 +22,11 @@
 /**
  * Controller used to manage blog contents in the backend.
  *
+ * Please note that the application backend is developed manually for learning
+ * purposes. However, in your real Symfony application you should use any of the
+ * existing bundles that let you generate ready-to-use backends without effort.
+ * See http://knpbundles.com/keyword/admin
+ *
  * @Route("/admin/post")
  * @Security("has_role('ROLE_ADMIN')")
  *
@@ -52,7 +57,7 @@ public function indexAction()
 
         return $this->render('admin/blog/index.html.twig', array('posts' => $posts));
     }
-    
+
     /**
      * Creates a new Post entity.
      *
diff --git a/src/AppBundle/DataFixtures/ORM/LoadFixtures.php b/src/AppBundle/DataFixtures/ORM/LoadFixtures.php
@@ -20,7 +20,9 @@
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
- * Defines the sample data to load in the database when executing this command:
+ * Defines the sample data to load in the database when running the unit and
+ * functional tests. Execute this command to load the data:
+ *
  *   $ php app/console doctrine:fixtures:load
  *
  * See http://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html

Original file line number	Diff line number	Diff line change
`@@ -22,6 +22,11 @@`
`22`	`22`	`/**`
`23`	`23`	`* Controller used to manage blog contents in the backend.`
`24`	`24`	`*`
	`25`	`+ * Please note that the application backend is developed manually for learning`
	`26`	`+ * purposes. However, in your real Symfony application you should use any of the`
	`27`	`+ * existing bundles that let you generate ready-to-use backends without effort.`
	`28`	`+ * See http://knpbundles.com/keyword/admin`
	`29`	`+ *`
`25`	`30`	`* @Route("/admin/post")`
`26`	`31`	`* @Security("has_role('ROLE_ADMIN')")`
`27`	`32`	`*`
`@@ -52,7 +57,7 @@ public function indexAction()`
`52`	`57`
`53`	`58`	`return $this->render('admin/blog/index.html.twig', array('posts' => $posts));`
`54`	`59`	`}`
`55`		`-`
	`60`	`+`
`56`	`61`	`/**`
`57`	`62`	`* Creates a new Post entity.`
`58`	`63`	`*`